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

[github-actions]

Summary

Automated CLI consistency inspection found 6 inconsistencies across commands and documentation that should be addressed for better user experience and accuracy.

Breakdown by Severity

• High: 0
• Medium: 2 (incorrect/misleading documentation)
• Low: 4 (minor inconsistencies)

Inspection Details

• Total Commands Inspected: 35 (all top-level commands and subcommands via --help)
• Commands with Issues: 6
• Date: 2026-05-08
• Method: Executed all CLI commands with --help flags and cross-referenced against docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• All flag descriptions are consistently terminated without periods
• Flag naming is consistent across similar commands (-r/--repo, -e/--engine, -j/--json, -d/--dir, -v/--verbose)
• All commands have usage examples
• Engine options list (copilot, claude, codex, gemini, crush) is consistent across all commands that expose --engine
• --repeat flag semantics are consistent between run and trial
• --artifacts valid sets are consistent between audit and logs

⚠️ Issues found:

• Incorrect docs example for --codespaces flag
• Confusing --after flag name in logs command
• Inconsistent bullet description for secrets bootstrap
• Asymmetric documentation between disable and enable
• Redundant alias flags --last / --count without preference guidance
• Undocumented behavior of mcp add with only a workflow argument

Detailed Findings

1. gh aw init --codespaces incorrect usage in docs

Commands Affected: init
Priority: Medium
Type: Incorrect documentation

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

gh aw init --codespaces ""               # Configure Codespaces for current repo only
gh aw init --codespaces repo1,repo2       # Codespaces with additional repos

Current docs (docs/src/content/docs/setup/cli.md, line 139):

gh aw init --codespaces                 # Configure devcontainer for current repo
gh aw init --codespaces repo1,repo2     # Configure devcontainer for additional repos

Verification:

$ ./gh-aw init --codespaces
✗ flag needs an argument: --codespaces

Issue: The documentation shows --codespaces without a value, but the flag is a string type that requires an explicit value. Using it without a value produces an error. The source code also confirms with the comment: // Trim the codespace repos string (explicit value required; use --codespaces "" for current repo only)

Suggested Fix: Update the docs example from gh aw init --codespaces to gh aw init --codespaces ""

---

2. gh aw logs --after flag name vs description mismatch

Commands Affected: logs
Priority: Medium
Type: Misleading flag naming

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

--after string   (Cache eviction) Evict locally cached run folders for runs before this date...

And from examples:

gh aw logs --after -1w    # Evict local cache older than 1 week before downloading runs

Issue: The flag is named --after but its description says it evicts runs before the specified date. A user reading --after -1w would reasonably expect it to affect runs after 1 week ago, but it actually evicts runs older than 1 week ago (i.e., before the point 1 week ago). Compare to --start-date which filters for runs after a date — the naming convention is reversed between the two flags.

Suggested Fix: Update the description to clarify direction more explicitly, e.g. "Evict locally cached run folders older than this date" or update the example comment to "Keep only cache from the last week (evict runs older than 1 week)".

---

3. gh aw secrets parent bullet uses "Validate" but bootstrap --help says "Analyze"

Commands Affected: secrets, secrets bootstrap
Priority: Low
Type: Inconsistent terminology

Current CLI output (from ./gh-aw secrets --help):

• bootstrap - Validate and configure all required secrets for workflows

Current CLI output (from ./gh-aw secrets bootstrap --help):

Analyze all workflows in the repository to determine which secrets are required...

Issue: The parent secrets command describes bootstrap as "Validate and configure" but the command itself says "Analyze". These are different verbs with slightly different implications.

Suggested Fix: Update the parent bullet to: • bootstrap - Analyze and configure all required secrets for workflows

---

4. gh aw disable documents run cancellation but gh aw enable has no equivalent note

Commands Affected: disable, enable
Priority: Low
Type: Asymmetric documentation

Current CLI output (from ./gh-aw disable --help):

Disable one or more workflows by ID, or all workflows if no IDs are provided.

Any in-progress runs will be cancelled before disabling.

Current CLI output (from ./gh-aw enable --help):

Enable one or more workflows by ID, or all workflows if no IDs are provided.

Issue: disable explicitly documents that in-progress runs are cancelled, but enable has no comparable note about what happens to currently running workflows when called.

Suggested Fix: Add a note to enable --help such as "Note: Enabling a workflow does not affect currently running workflow runs" to set clear expectations.

---

5. gh aw logs has both --last and --count/-c as aliases without preference guidance

Commands Affected: logs
Priority: Low
Type: Redundant flags without preference guidance

Current CLI output (from ./gh-aw logs --help):

-c, --count int   Maximum number of matching workflow runs to return (after applying filters) (default 10)
    --last int    Alias for --count: number of recent runs to download

Issue: Two flags (--count/-c and --last) do the same thing. Users don't know which to prefer for scripts and documentation.

Suggested Fix: Update --last description to: "Alias for --count (prefer --count/-c in scripts)".

---

6. gh aw mcp add behavior with only workflow argument (no server) is undocumented

Commands Affected: mcp add
Priority: Low
Type: Missing documentation

Current CLI output (from ./gh-aw mcp add --help):

Usage:
  gh aw mcp add [workflow] [server] [flags]

Examples:
  gh aw mcp add                   # List available MCP servers
  gh aw mcp add weekly-research makenotion/notion-mcp-server  # Add Notion MCP server

Issue: Both [workflow] and [server] are shown as optional in the Usage. An example exists for zero arguments (lists servers). But there is no documentation of what happens when only [workflow] is provided without [server].

Suggested Fix: Add an example or note clarifying the behavior when only a workflow is specified, e.g. gh aw mcp add weekly-research # List available MCP servers (workflow argument ignored without server).

Generated by CLI Consistency Checker · ● 13.6M · ◷

• expires on May 10, 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 · ● 113.5K · ◷

[github-actions]

This issue was automatically closed because it expired on 2026-05-10T13:50:13.287Z.

Closed by Workflow