[cli-consistency] CLI Consistency Issues - 2026-05-07

[github-actions]

Summary

Automated CLI consistency inspection found 3 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.

Breakdown by Severity

• High: 0
• Medium: 1 (Non-standard terminology)
• Low: 2 (Minor inconsistencies)

Inspection Details

• Total Commands Inspected: 23
• Commands with Issues: 3
• Date: 2026-05-07
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Command descriptions (all clear and accurate)
• Flag naming consistency across commands
• Examples accuracy (all examples use valid flags and correct syntax)
• Documentation of --repo, --engine, --verbose, --json, --help flags across applicable commands
• Technical accuracy of workflow-id explanations (consistent across all commands)
• Subcommand groupings and hierarchy
• compile --help: --watch flag correctly documented with short form -w

⚠️ Issues found:

• Non-standard "write+" access level terminology in mcp-server
• Potentially misleading first example comment in mcp list-tools
• Bullet character • formatting in pr subcommand list

Detailed Findings

1. Non-standard "write+" Terminology in mcp-server

Commands Affected: mcp-server
Priority: Medium
Type: Inconsistent terminology

Current Output (from running ./gh-aw mcp-server --help):

- logs        - Download and analyze workflow logs (requires write+ access)
- audit       - Investigate a workflow run, job, or step and generate a report (requires write+ access)
...
mounted but will return permission denied errors if the actor lacks write+ access.

Issue: The term write+ is informal shorthand not used in GitHub's standard documentation. It appears 3 times in the command's help text. GitHub's standard phrasing is "write access or higher" or "write permission or above".

Suggested Fix: Replace all instances of write+ with write access or higher:

• "requires write+ access" → "requires write access or higher"
• "the actor lacks write+ access" → "the actor lacks write access or higher"

---

2. Misleading Comment on First mcp list-tools Example

Commands Affected: mcp list-tools
Priority: Low
Type: Potentially misleading documentation

Current Output (from running ./gh-aw mcp list-tools --help):

Examples:
  gh aw mcp list-tools --server github                    # Find workflows with 'github' MCP server
  gh aw mcp list-tools weekly-research --server github    # List tools for 'github' server in weekly-research.md

Issue: The command is named list-tools, but its first example (without a workflow argument) performs a workflow discovery operation rather than listing tools. The comment # Find workflows with 'github' MCP server is accurate, but the command name creates an expectation of always listing tools. A user seeing the command name alone may not realize the no-workflow-arg mode finds workflows instead of tools.

Suggested Fix: Make the distinction clearer either in the short description or in the example comment:

  gh aw mcp list-tools --server github                    # Find workflows using 'github' MCP server (no tools listed without workflow)

Alternatively, add a note to the description: "When no workflow is provided, lists workflows that contain the specified server instead of listing tools."

---

3. Bullet Character • in pr Subcommand List

Commands Affected: pr
Priority: Low
Type: Minor formatting inconsistency

Current Output (from running ./gh-aw pr --help):

Available subcommands:
  • transfer - Transfer a pull request to another repository

Issue: The pr parent command uses Unicode bullet character • in its "Available subcommands" description, while all other parent commands (e.g., mcp) use the standard cobra-generated Available Commands: block without manual bullet formatting. This creates a minor visual inconsistency.

Suggested Fix: Remove the manual "Available subcommands" bullet list from the pr Long description and let cobra generate the standard Available Commands: section automatically. Or at minimum remove the • prefix and use plain text.

Generated by CLI Consistency Checker · ● 8.1M · ◷

• expires on May 9, 2026, 1:50 PM UTC

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · ● 64.6K · ◷