Repository navigation
Description
Summary
Automated CLI consistency inspection found 5 inconsistencies in command help text that should be addressed for better user experience.
Breakdown by Severity
- High: 0
- Medium: 2 (Inconsistent formatting, undocumented flag format)
- Low: 3 (Minor inconsistencies)
Inspection Details
- Total Commands Inspected: 33 (all top-level commands + subcommands)
- Commands with Issues: 5
- Date: 2026-05-13
- Method: Executed all CLI commands with
--helpflags and analyzed actual output
Findings Summary
✅ No issues found in these areas:
- Flag naming consistency across commands
- Global flags (
--banner,-v/--verbose) present on all commands - Workflow ID description consistency across compile/disable/enable/etc.
--repoflag present and described consistently- Examples quality and coverage
- Help flag (
-h/--help) present everywhere - Short descriptions are consistent and clear
- Inconsistent bullet style in subcommand listings
logs --afterflag description incomplete delta format documentationmcp inspectwithout args overlaps silently withmcp listupdatemissing--disable-security-scannerflag present inaddandtrialmcp list-toolsno guidance when invoked without--server
Detailed Findings
1. Inconsistent Bullet Style in Subcommand Listings
Commands Affected: pr
Priority: Medium
Type: Inconsistency
Current Output (from ./gh-aw pr --help):
Available subcommands:
- transfer - Transfer a pull request to another repository
Expected (matching style from ./gh-aw mcp --help, ./gh-aw secrets --help, ./gh-aw project --help):
Available subcommands:
• transfer - Transfer a pull request to another repository
Issue: The pr command uses - dashes to list subcommands in its long description, while mcp, secrets, and project all use • (bullet) characters. This creates visual inconsistency across the CLI.
Suggested Fix: Update the pr command's long description to use • instead of - for subcommand listing, matching the convention used in mcp, secrets, and project.
2. logs --after Flag Description Has Incomplete Delta Format Documentation
Commands Affected: logs
Priority: Medium
Type: Incomplete documentation
Current Output (from ./gh-aw logs --help):
--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.
Comparison with --start-date and --end-date:
--start-date string Filter runs created after this date (YYYY-MM-DD or delta like -1d, -1w, -1mo)
--end-date string Filter runs created before this date (YYYY-MM-DD or delta like -1d, -1w, -1mo)
Example in help text that uses undocumented format:
gh aw logs --after -30d # Evict local cache older than 30 days before downloading runs
Issue: Two problems:
--afterdescription omits-1das a valid delta format, while--start-dateand--end-dateboth document it.- The
--afterexamples use-30d(a multi-digit day count) which is not mentioned in the flag description at all.
Suggested Fix: Update the --after flag description to read: Accepts deltas like -1d, -1w, -30d, -1mo, or an absolute date YYYY-MM-DD.
3. mcp inspect Without Arguments Silently Overlaps With mcp list
Commands Affected: mcp inspect, mcp list
Priority: Low
Type: Confusing overlap
Current Output (from ./gh-aw mcp inspect --help):
When no workflow is provided, this command lists workflows that have MCP server configurations.
Current Output (from ./gh-aw mcp list --help):
When no workflow ID/file is specified, lists all workflows that contain MCP server configurations.
Issue: Both mcp inspect and mcp list produce a listing of workflows with MCP servers when called without arguments. A user unsure which command to use may be confused about the difference. The mcp parent help also shows both commands without clarifying when to use inspect vs list at the listing stage.
Suggested Fix: Consider updating mcp inspect to require a workflow argument (returning an error with helpful guidance) when called without one, and directing users to mcp list to discover workflows. Alternatively, add a note to mcp inspect --help clarifying that mcp list is the preferred command for discovery.
4. update Missing --disable-security-scanner Flag
Commands Affected: update
Priority: Low
Type: Missing flag
Current add flags (from ./gh-aw add --help):
--disable-security-scanner Disable security scanning of workflow markdown content
Current trial flags (from ./gh-aw trial --help):
--disable-security-scanner Disable security scanning of workflow markdown content
Issue: Both add and trial have --disable-security-scanner to bypass security scanning of workflow markdown content, but update (which also fetches and installs remote workflow content) does not. Users who need to suppress security scanning during workflow updates have no way to do so.
Suggested Fix: Add --disable-security-scanner flag to the update command if it performs equivalent security scanning on fetched content, or document why it is intentionally absent.
5. mcp list-tools Gives Unhelpful Error When Invoked Without --server
Commands Affected: mcp list-tools
Priority: Low
Type: Missing guidance
Current flag (from ./gh-aw mcp list-tools --help):
--server string MCP server name to list tools for (required)
Issue: The --server flag is marked (required) in the description text (manually added string, not a Cobra MarkFlagRequired call). Running gh aw mcp list-tools without --server produces a generic error with no helpful guidance pointing the user to the correct flag. The first example in the help text (gh aw mcp list-tools --server github) shows the required flag, but users may miss it.
Also, the first example description says "Search for workflows containing the 'github' MCP server" — this is a different behavior (searching) vs the rest of the examples (listing tools) — the description could be clarified.
Suggested Fix: Either use cmd.MarkFlagRequired("server") to get Cobra to produce a proper "required flag not set" error, or add a check that prints a helpful message like "--server is required. Use 'gh aw mcp list' to discover available servers."
Generated by CLI Consistency Checker · ● 9.6M · ◷
- expires on May 15, 2026, 1:58 PM UTC
Activity
github-actions commentedon May 13, 2026
🍪 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! 🍪