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

[github-actions]

Summary

Inspection of the gh-aw CLI help output (/tmp/gh-aw/agent/all-help.txt, 21,775 lines / 1.5 MB, 426 raw help captures / 103 unique command variants) and comparison against docs/src/content/docs/setup/cli.md (1,023 lines) found a small number of genuine inconsistencies. No typos or grammar issues were found in the sampled help text; the CLI's help output is generally clean and consistent (flag descriptions consistently omit trailing periods, -j/--json and -o/--output naming is uniform across commands, and most --no-* flags follow a "Skip X" phrasing).

Severity breakdown: 1 high, 2 medium, 1 low

Note on methodology: The Rig custom harness (node .github/skills/rig/rig.ts) could not be executed in this run — invoking it requires a COPILOT_CONNECTION_TOKEN connecting to the local Copilot SDK runtime, which is not exposed to this workflow's sandbox (AUTHENTICATION_FAILED when calling the Copilot engine). The three analyses (typo/grammar, flag consistency, docs-vs-help) were instead performed directly against the pre-collected help output and docs source using targeted grep/diff comparisons, which is a strict subset of what an LLM-based harness could surface. This is a tooling limitation worth flagging to whoever maintains the pre-agent-steps sandbox config for this workflow.

Findings by category

1. Docs vs Help: compile command missing --shellcheck from documented Options list (High)

• Affected command: gh aw compile
• Exact CLI help output (compile.txt line 91):

        --shellcheck                  Run shellcheck linting of run step scripts
  

• Docs (docs/src/content/docs/setup/cli.md line 338, the **Options:** line for compile) lists 37 flags but does not include --shellcheck, even though --pyflakes-style script-linting integrations are documented for the lint command (line 389: **Options:** --dir/-d, --shellcheck, --pyflakes).
• Expected: compile's Options summary line should include --shellcheck (and verify --pyflakes is/isn't also present on compile, since lint documents both together).
• Actual: --shellcheck is silently omitted from the compile docs Options list.
• Suggested fix: Add --shellcheck to the Options summary for compile in docs/src/content/docs/setup/cli.md (and confirm whether --pyflakes also applies to compile; if so, add it too).
• Priority: High — this is a real, user-facing flag not documented for the command where it appears in --help.

2. Docs: Global Options table omits --version flag (Medium)

• Affected command: root gh aw
• Exact CLI help output (main.txt):

  Flags:
        --banner    Display ASCII logo banner with purple GitHub color theme
    -h, --help      Show help for gh aw
    -v, --verbose   Enable verbose output showing detailed information
        --version   Print the current version
  

• Docs (docs/src/content/docs/setup/cli.md lines 126-130, "## Global Options" table) lists only -h/--help, -v/--verbose, and --banner. --version is omitted from the table, though a separate sentence below it ("Use gh aw version to print the current version.") references the version subcommand instead of the --version flag.
• Expected: The Global Options table should include a row for --version (Print the current version), matching the other three global flags.
• Actual: --version flag is undocumented in the Global Options table.
• Suggested fix: Add | \--version` | Print the current version |` to the Global Options table.
• Priority: Medium.

3. Flag consistency: -f, --force has divergent semantics across commands (Medium)

• Affected commands: add, deploy, new vs. update vs. compile
• Exact quoted text:
  • add.txt: -f, --force Overwrite existing workflow files without confirmation
  • deploy.txt: -f, --force Overwrite existing workflow files without confirmation
  • new.txt: -f, --force Overwrite existing workflow files without confirmation
  • update.txt: -f, --force Force update even if no changes are detected
  • compile.txt: -f, --force Force overwrite of existing dependency files (only applies when --dependabot is set; e.g., dependabot.yml)
• Issue: The same short/long flag pair (-f/--force) means three different things depending on the command: (a) "overwrite existing workflow files", (b) "force an update even if no changes detected", (c) "force overwrite of dependency files, gated by another flag". This can mislead users who infer behavior for one command from having seen --force on another.
• Expected: Either use distinct flag names for semantically distinct behaviors (e.g., --force-update on update), or ensure the help text for each consistently signals what exactly gets overwritten/forced.
• Suggested fix: Keep --force for the common "overwrite files" case, and consider renaming update --force's underlying behavior to something like --force-update (with -f reserved), or at minimum cross-reference in the docs that --force is command-specific.
• Priority: Medium — not a bug, but a naming-consistency smell that increases cognitive load for CLI users.

4. Flag description wording: inconsistent phrasing for --no-* negation flags (Low)

• Affected commands: update
• Exact quoted text:
  • --no-compile Skip recompiling workflows during update (do not modify lock files)
  • --no-merge Override local changes with upstream version instead of merging
  • --no-redirect Refuse updates when redirect frontmatter is present
  • --no-release-bump Restrict automatic major version bumps to core actions/* only (non-core actions are left as-is)
• Issue: Most --no-* flags across the CLI use a "Skip X" phrasing (--no-gitattributes, --no-security-scanner, --no-stop-after, --no-remove-orphans, etc.), but update's --no-merge, --no-redirect, and --no-release-bump describe the resulting behavior rather than what's being skipped, breaking the pattern.
• Suggested fix: Normalize descriptions to the "Skip X" / "Disable X" style used elsewhere, e.g. --no-merge → "Skip merging; override local changes with upstream version" for scanability.
• Priority: Low — cosmetic/documentation-style consistency only.

Inspection metadata

• Commands inspected: All gh aw commands and subcommands captured in /tmp/gh-aw/agent/help-output/ (426 raw help captures, 103 unique after de-duplication), cross-referenced against /tmp/gh-aw/agent/all-help.txt (21,775 lines) and docs/src/content/docs/setup/cli.md (1,023 lines).
• Date: 2026-08-04
• Method: Direct grep/diff-based comparison of pre-collected help output vs. documentation source (Rig harness unavailable in this sandbox — see methodology note above).

Generated by ✅ CLI Consistency Checker · auto · 184.5 AIC · ⌖ 3.88 AIC · ⊞ 7.3K · ◷

• expires on Aug 6, 2026, 6:04 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot\n\nI've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.\n\nIf assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.\n\nOm nom nom! 🍪

🍪 Om nom nom by Issue Monster · gpt54 · 2.73 AIC · ⌖ 8.54 AIC · ⊞ 10.1K · ◷