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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0 (Breaks functionality)
• Medium: 2 (Misleading or inconsistent UX)
• Low: 3 (Minor inconsistencies)

Inspection Details

• Total Commands Inspected: 32 (all top-level and subcommands)
• Commands with Issues: 5
• Date: 2026-05-12
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming conventions (consistent use of -h, -v, -r, -j, -e, -d, -f short flags)
• Help text grammar and spelling
• Example formatting and accuracy
• Error messages and usage strings
• Global flags (--banner, -v, --verbose)

⚠️ Issues found:

• Misleading flag constraint hint in forecast
• Missing --json flag in trial (present in parallel command run)
• Inconsistent version command description across contexts
• mcp list-tools --server not marked as required
• mcp group description for list-tools slightly inaccurate

Detailed Findings

1. gh aw forecast --days Misleadingly Restricts Values to "(7 or 30)"

Command Affected: gh aw forecast
Priority: Medium
Type: Misleading flag description

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

--days int        Historical window in days used to sample run history (7 or 30) (default 30)

Issue: The hint (7 or 30) implies these are the only accepted values, but the flag is typed as int and accepts any positive integer. Users may unnecessarily limit themselves to only these two values.

Suggested Fix: Change to a more accurate description:

--days int        Historical window in days used to sample run history (default 30)

Or if only 7/30 are meaningful:

--days int        Historical window in days used to sample run history; use 7 for weekly or 30 for monthly (default 30)

---

2. gh aw trial Missing --json Flag (Present in Parallel gh aw run)

Commands Affected: gh aw trial (missing), gh aw run (has it)
Priority: Medium
Type: Flag inconsistency between parallel commands

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

  -j, --json                    Output results in JSON format

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

Flags:
      --append string                   ...
      --auto-merge-prs                  ...
      ...
      -y, --yes                         Skip confirmation prompts

(No --json / -j flag present)

Issue: gh aw run and gh aw trial are parallel commands (both dispatch workflows). run has --json output support, but trial does not. Users scripting trial runs cannot get machine-readable output.

Suggested Fix: Add -j, --json flag to gh aw trial for consistent programmatic use.

---

3. gh aw version Description Inconsistency

Command Affected: gh aw version
Priority: Low
Type: Inconsistent description across contexts

Current Output (in main ./gh-aw --help under Utilities):

  version          Show gh aw extension version information

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

Show the installed version of the gh aw extension.

Issue: The short description in the main help ("Show gh aw extension version information") differs subtly from the command's own help text ("Show the installed version of the gh aw extension."). While minor, Cobra uses the Short field in both places — these should match.

Suggested Fix: Align to a single consistent description, e.g.:

Show the installed version of the gh aw extension

---

4. gh aw mcp list-tools --server Not Marked as Required

Command Affected: gh aw mcp list-tools
Priority: Low
Type: Misleading flag definition

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

Flags:
  -h, --help            Show help for gh aw mcp list-tools
      --server string   MCP server name to list tools for

Issue: The --server flag is not marked as required, yet the command's purpose is to list tools for a specific server. Without --server, the command behavior is undefined by the help text. The first example (gh aw mcp list-tools --server github) works without a workflow arg, but omitting --server entirely is not documented.

Suggested Fix: Either mark the flag as (required) or add an example showing what happens when --server is omitted:

  gh aw mcp list-tools                       # Show usage (server required)

---

5. gh aw mcp Group: list-tools Description Inaccurate

Command Affected: gh aw mcp (group help), gh aw mcp list-tools
Priority: Low
Type: Inaccurate short description

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

  list-tools List available tools for a specific MCP server

Issue: The description says "for a specific MCP server" which implies a specific server is always needed. However, gh aw mcp list-tools --server github (without a workflow) searches across all workflows for the server named github. The command can operate in a discovery mode, not just per-server mode.

Suggested Fix: Update the short description to:

  list-tools List tools for a specific MCP server in a workflow

Generated by CLI Consistency Checker · ● 11.5M · ◷

• expires on May 14, 2026, 1:54 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 · ● 178.7K · ◷