[cli-consistency] CLI Consistency Issues - 2026-07-09

[github-actions]

CLI Consistency Issues — Inspection Report

Date: 2026-07-09
Method: Live gh-aw --help output compared against docs/src/content/docs/setup/cli.md
Commands inspected: 28 (all top-level commands + subcommands)

Severity Breakdown

Severity	Count
🔴 High	1
🟡 Medium	5
🟢 Low	6

---

🔴 High Priority

H1 — completion subcommand description incorrect

Command: gh aw completion
Docs (line 852): **Subcommands:** \install`, `uninstall`, `bash`, `zsh`, `fish`, `powershell``
Actual CLI:

Available Commands:
  install   Install shell completion for the detected shell
  uninstall Uninstall shell completion for the detected shell

bash, zsh, fish, and powershell are positional arguments, not subcommands. Running gh aw completion bash generates the bash completion script (works), but they don't appear under Available Commands and have no own --help page. Documenting them as "subcommands" misrepresents the CLI structure and may confuse users.
Suggested fix: Change the docs line to: **Shell arguments:** \bash`, `zsh`, `fish`, `powershell` — Subcommands: `install`, `uninstall``

---

🟡 Medium Priority

5 medium-severity findings (click to expand)

M1 — new command description claims auto-open in editor

Command: gh aw new
Docs (line 209): "Create a workflow template in \.github/workflows/`. Opens for editing automatically." **Actual CLI help:** No mention of opening an editor. The command creates a file but does not mention opening it for editing. This could be environment-dependent (e.g.$EDITOR) but is not documented in the flags or help text. **Suggested fix:** Qualify this statement: "Opens for editing automatically when $EDITOR` is set, or provide a note about when/how editor auto-open works.

M2 — mcp inspect advanced flags not documented

Command: gh aw mcp inspect
Docs (line 783): gh aw mcp inspect workflow # Inspect and test servers
Actual CLI flags:

--check-secrets   Check GitHub Actions repository secrets for missing secrets
--inspector       Launch the official `@modelcontextprotocol/inspector` tool
--server string   Filter to inspect only the specified MCP server
--tool string     Show detailed information about a specific tool (requires --server)

The docs show only a single brief example and don't list these flags or their descriptions. The --inspector, --check-secrets, --server, and --tool flags are all undocumented in the CLI reference page.
Suggested fix: Add a proper Options list and expanded examples for mcp inspect.

M3 — secrets set options list missing -r shorthand

Command: gh aw secrets set
Docs (line 246): **Options:** \--repo`, `--value`, `--value-from-env`, `--api-url` **Actual CLI flag:**-r, --repo string The docs list--repobut omit the-rshorthand. All other commands consistently document shorthand aliases (e.g.--repo/-r). **Suggested fix:** Change to --repo/-r` to match the convention used everywhere else.

M4 — mcp add docs example uses wrong syntax

Docs (lines 784–785):

gh aw mcp add                              # List available MCP servers from the registry
gh aw mcp add <workflow> <server>          # Add an MCP server to a workflow

Actual CLI usage:

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

The docs use angle-bracket notation <workflow> <server> suggesting required args, but the CLI shows them as optional [workflow] [server]. Also, the docs don't show any of the flags (--transport, --registry, --tool-id) that the CLI exposes, nor the advanced examples from the actual help.
Suggested fix: Update examples to use [workflow] notation and add the options list.

M5 — audit artifacts default discrepancy between logs and audit docs

Command: gh aw audit
Docs (line 511): The \--artifacts` flag selects which artifact sets to download (default: `all`)... **Actual CLI flag description:**--artifacts strings Artifact sets to download (default: all, because auditing requires comprehensive artifacts for analysis). **logsCLI flag:**--artifacts strings Artifact sets to download (default: usage — compact summary for faster downloads). The docs conflate the audit and logs artifact defaults. The audit section at line 511 (which is actually within theaudit section) correctly saysall, but the phrasing doesn't make clear that auditdefaults toallwhilelogsdefaults tousage. This causes confusion when users switch between commands. **Suggested fix:** Add a note clarifying the difference: auditdefaults toall; logsdefaults tousage`.

---

🟢 Low Priority

6 low-severity findings (click to expand)

L1 — mcp inspect docs section missing flags/options block

The mcp section only has one line for inspect but no Options: block, unlike every other command in the docs. (Covered partially in M2 above; this is the structural gap.)

L2 — experiments docs missing --json in analyze example

Docs (lines 631–635):

gh aw experiments                          # List experiment workflow branches
gh aw experiments list --json             # List all experiments in JSON format
gh aw experiments analyze my-workflow     # Analyze one experiment workflow
gh aw experiments analyze my-workflow --repo owner/repo

Actual CLI example:

gh aw experiments analyze my-workflow --json       # Output in JSON format
gh aw experiments analyze my-workflow --repo owner/repo  # Analyze in a specific repository

The docs example omits the --json flag for analyze, which is shown in the actual CLI examples.
Suggested fix: Add gh aw experiments analyze my-workflow --json to the docs examples.

L3 — run docs options list missing --repo/-r flag

Docs (line 387) options list: --repeat, --push, --ref, --enable-if-needed, --json/-j, --auto-merge-prs, --dry-run, --engine/-e, --raw-field/-F, --repo/-r, --approve
Actually --repo/-r is listed. ✓ — Noting for completeness; no change needed here.

L4 — add docs examples differ from CLI examples (narrower set)

Docs examples (lines 178–183): 6 examples
CLI examples: 12 examples (includes local ./my-workflow.md, ./.md, packages/, etc.) The docs show fewer examples than the CLI. While docs don't need to be exhaustive, the useful local-file examples (./my-workflow.md, ./.md) and the package examples are missing from the docs and represent real user scenarios. **Suggested fix:** Add local file and wildcard examples to the add` docs section.

L5 — outcomes history docs example inconsistency

Docs (lines 565–568):

gh aw outcomes history                               # Score recent issues and PRs
gh aw outcomes history --source issues --limit 100  # Only issues, limited to 100 items
gh aw outcomes history --repo owner/repo --json     # JSON output for another repo

Actual CLI:

gh aw outcomes history
gh aw outcomes history --source issues --limit 100
gh aw outcomes history --repo owner/repo --json

The docs and CLI examples match well here. Minor: docs omit verbose flag (-v) example shown in the parent outcomes command docs at line 554: gh aw outcomes 1234567890 -v # Verbose output.

L6 — logs and audit docs both say "default: all" for artifacts; logs default is actually usage

Context: In the logs section (line 480), the Options list says --last (alias for --count) is included. But --last is not described elsewhere in the logs section body. The CLI help explains: --last int Alias for --count: number of recent runs to download. This undocumented alias deserves a brief mention in the logs section body for discoverability.

---

Inspection Metadata

• Source of truth: Live CLI output from ./gh-aw [cmd] --help for all 28 commands/subcommands
• Docs compared: docs/src/content/docs/setup/cli.md (52.7 KB)
• Date: 2026-07-09
• Workflow run: 29023464297
• Note: The all-help.txt pre-collection file was empty (0 bytes); CLI output was collected directly by running the binary.

Generated by ✅ CLI Consistency Checker · 153.6 AIC · ⌖ 13.8 AIC · ⊞ 4.4K · ◷

• expires on Jul 11, 2026, 6:17 AM UTC-08:00

[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 · 1.36 AIC · ⌖ 6.03 AIC · ⊞ 8.4K · ◷