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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0 (Breaks functionality)
• Medium: 1 (Inconsistent/misleading documentation)
• Low: 5 (Minor inconsistencies)

Issue Categories

1. Missing no-arg behavior documentation (1 command): mcp inspect description doesn't mention its no-arg listing behavior
2. Inaccurate parent command description (2 commands): project and pr have misleading parent descriptions
3. Capitalization inconsistency (1 command): completion uses inconsistent casing for "powershell"
4. Misleading example comments (1 command): logs --after cache maintenance examples suggest delete-only behavior
5. Minor grammar (1 command): init --codespaces description missing "the" articles

Inspection Details

• Total Commands Inspected: 28 (including all subcommands)
• Commands with Issues: 5
• Date: 2026-05-06
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• All flag names are consistent across equivalent commands (--repo, -r, --engine, -e, etc.)
• --help (-h) and --verbose (-v) are consistently available
• Command descriptions are clear and grammatically correct overall
• Examples are present and well-structured for all commands
• No duplicate command names or aliases detected
• File paths (.github/workflows) are consistently referenced

⚠️ Issues found:

• mcp inspect: no-arg behavior not described in long description
• project: parent command description says "Manage" but only new subcommand exists
• completion: "powershell" capitalization inconsistency
• logs: --after "Cache maintenance" example comments are incomplete
• pr: parent command says "provides tools" (plural) for a single subcommand
• init: minor grammar issue in --codespaces description

Detailed Findings

1. gh aw mcp inspect — No-arg behavior not documented in long description

Commands Affected: gh aw mcp inspect
Priority: Medium
Type: Inconsistency between description and behavior

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

Inspect MCP servers used by a workflow and display available tools, resources, and roots.

This command starts each MCP server configured in the workflow, queries its capabilities,
and displays the results in a formatted table. It supports stdio, Docker, and HTTP MCP servers.
...
Examples:
  gh aw mcp inspect                    # List workflows with MCP servers
  gh aw mcp inspect weekly-research    # Inspect MCP servers in weekly-research.md

Issue: The long description says "Inspect MCP servers used by a workflow" and "This command starts each MCP server configured in the workflow" — both implying a workflow argument is required. However, the first example shows it accepts no arguments and lists workflows, exactly like gh aw mcp list. The no-arg behavior is only visible in the examples, not in the description itself. Additionally, the overlap with mcp list (which also lists workflows when called without args) is not clarified.

Suggested Fix: Add a sentence to the long description such as: "When called without a workflow argument, lists all workflows that have MCP server configurations (equivalent to mcp list)."

---

2. gh aw project — Parent command says "Manage" but only new subcommand exists

Commands Affected: gh aw project
Priority: Low
Type: Inaccurate description

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

Manage GitHub Projects V2 boards linked to repositories.

GitHub Projects V2 provides kanban-style project boards for tracking issues,
pull requests, and tasks across repositories.

This command allows you to create new projects owned by users or organizations
and optionally link them to specific repositories.

Available subcommands:
  • new - Create a new GitHub Project V2 board

Issue: The one-line summary says "Manage GitHub Projects V2 boards linked to repositories" but the only available subcommand is new (for creating projects). The word "Manage" implies read, update, and delete operations which aren't available. The body paragraph correctly says "create new projects" but the top-line description is misleading.

Suggested Fix: Change the short description to "Create GitHub Projects V2 boards for your repository."

---

3. gh aw completion — Inconsistent capitalization of "powershell"

Commands Affected: gh aw completion
Priority: Low
Type: Capitalization inconsistency

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

Supported shells: bash, zsh, fish, powershell

Examples:
  ...
  # Generate completion script for PowerShell
  gh aw completion powershell | Out-String | Invoke-Expression

  # Add to PowerShell profile for persistent completions
  echo 'gh aw completion powershell | Out-String | Invoke-Expression' >> $PROFILE

Issue: The "Supported shells" list uses lowercase powershell, but the comments in examples use PowerShell (Title Case). The command argument itself is powershell (lowercase), which is correct, but prose references are inconsistent.

Suggested Fix: Standardize prose references to PowerShell (matching Microsoft's official branding): "Supported shells: bash, zsh, fish, PowerShell"

---

4. gh aw logs --after — "Cache maintenance" example comments suggest delete-only behavior

Commands Affected: gh aw logs
Priority: Low
Type: Misleading example comments

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

  # Cache maintenance
  gh aw logs --after -1w                # Delete cached run folders older than 1 week
  gh aw logs --after -30d               # Delete cached run folders older than 30 days
  gh aw logs --after -1mo               # Delete cached run folders older than 1 month
  gh aw logs --after 2024-01-01         # Delete cached run folders older than 2024-01-01

And the flag description:

--after string  (Cache eviction) Evict locally cached run folders for runs before this date,
                prior to downloading. Accepts deltas like -1w, -1mo, or an absolute date
                YYYY-MM-DD. Unlike --start-date, this only clears local cache and does not
                filter which runs are fetched.

Issue: The "Cache maintenance" example comments say only "Delete cached run folders older than X", but the flag description clarifies that downloads also happen (it clears local cache "prior to downloading"). A user who wants to purge old cache without downloading new logs would be misled by these examples. The flag description is accurate; the example comments are not.

Suggested Fix: Update comments to reflect the combined behavior, e.g.:

gh aw logs --after -1w    # Evict cache older than 1 week, then download new runs

Or add a note that --after always downloads; for cache-only eviction a different approach may be needed.

---

5. gh aw pr — Parent command says "provides tools" (plural) for single subcommand

Commands Affected: gh aw pr
Priority: Low
Type: Minor inaccuracy

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

Pull request management utilities for transferring PRs between repositories.

This command provides tools for transferring pull requests from one repository
to another, including the code changes, title, and body.

Issue: "provides tools" (plural) implies multiple capabilities but only one subcommand (transfer) exists.

Suggested Fix: "This command provides a tool for transferring pull requests..." (singular), or rephrase to "This command transfers pull requests from one repository to another..."

---

6. gh aw init — Missing "the" articles in --codespaces description

Commands Affected: gh aw init
Priority: Low
Type: Minor grammar

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

With --codespaces flag:
- Configures permissions for current repo: actions:write, ...
- Configures permissions for additional repos (in same org): actions:read, ...

Issue: Both bullet points are missing the article "the" before "current repo" and "same org".

Suggested Fix:

- Configures permissions for the current repo: actions:write, ...
- Configures permissions for additional repos (in the same org): actions:read, ...

Generated by CLI Consistency Checker · ● 14.9M · ◷

• expires on May 8, 2026, 1:53 PM UTC

[pelikhan]

/q do a deep analyzis on the token usage and mcp tool calls and optimize. Add guardrails to avoid excessive useage.

[github-actions]

🎩 Mission equipment ready! Q has optimized your workflow. Use wisely, 007! 🔫

[github-actions]

Issue created: #30636

🎩 Equipped by Q

[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 · ● 58.4K · ◷