[cli-consistency] CLI Consistency Issues - 2026-06-22

[github-actions]

Summary

CLI inspection on 2026-06-22 found 23 issues across help text, flag naming, and docs.

Severity	Count
🔴 High	5
🟡 Medium	11
🟢 Low	7

Scope: 34 subcommands, 307 flags, docs/src/content/docs/setup/cli.md

---

🔴 High Severity

H1 — --skip-secret sole --skip-* flag; all 12 peers use --no-* (gh aw add-wizard)

CLI: --skip-secret Skip the API secret prompt...
Fix: rename to --no-secret

H2 — --disable-security-scanner and --disable-release-bump violate --no-* convention (add, deploy, update, trial)

These are boolean suppress flags identical in spirit to --no-gitattributes, --no-stop-after, etc.
Fix: rename to --no-security-scanner and --no-release-bump

H3 — audit --artifacts default wrong in docs

Docs (line 500): (default: \usage`)— CLI:(default: all) logsdefaults tousage; auditdefaults toall. Docs appear to have copy-pasted the wrong default. Fix: update docs to (default: `all`)foraudit`

H4 — logs --report-file flag missing from docs

CLI: --report-file string Write --format markdown output directly to this file path...
Not listed in docs options (line 469). Fix: add to docs.

H5 — outcomes history subcommand entirely undocumented

CLI: gh aw outcomes history with flags --limit int, --source string
The docs outcomes section (lines 536–547) mentions only the parent command.
Fix: add outcomes history subsection to docs.

---

🟡 Medium Severity

11 medium findings

M1 — mcp add docs show wrong syntax (missing workflow argument)

Docs: gh aw mcp add <server> — CLI usage: gh aw mcp add [workflow] [server]
With one arg, it parses as workflow, not server. Fix: gh aw mcp add <workflow> <server>

M2 — add subcommand description omits local file support

Main help: "...from repositories or local files" — add --help: "...from repositories"
Fix: add "or local files" to add description.

M3 — --no-firewall / --no-staged overload --no-* as filter operators in logs

All other --no-* flags mean "suppress a behavior." Here they mean "filter results."
Fix: rename to --without-firewall and --exclude-staged.

M4 — --dry-run descriptions diverge between sibling commands

run: "Validate workflow without actually triggering execution on GitHub Actions"
trial: "Show what would be done without making any changes"
Fix: standardize phrasing.

M5 — --force has different semantics across commands

add/deploy: overwrite files; compile: overwrite dependabot.yml only; update: force even if no changes.
Fix: align descriptions, consider --force-update for update.

M6 — --logical-repo descriptions inconsistent (compile vs trial)

compile adds odd (for trial mode) parenthetical and omits the default.
Fix: use the fuller trial description for both.

M7 — --timeout structure inconsistent (logs, trial, forecast)

Three different description formats; zero-disable phrasing differs (0 = no timeout vs 0 disables timeout).
Fix: standardize to "<Context> timeout in minutes (default N; 0 = no timeout)".

M8 — health docs mention "token usage, costs" not in CLI description

Docs (line 564) list these; CLI help omits them.
Fix: align or verify the feature exists.

M9 — audit docs show wrong output path

Docs (line 502): logs/run-{id}/ — Actual default: .github/aw/logs/run-{id}/
Fix: update docs.

M10 — Root --version flag absent from docs Global Options table

gh aw --version works but is not listed in the Global Options table (lines 111–117).

M11 — add-wizard missing 5 flags that add has

Missing: --append, --create-pull-request, --disable-security-scanner, --force, --name
add missing: --skip-secret
Fix: add missing flags or document the intentional subset.

---

🟢 Low Severity

7 low findings

L1 — Examples/Usage ordering: 6 commands embed Examples before Usage

new, compile, run, remove, disable, enable — all others follow standard cobra order.

L2 — version description inconsistency

Main help: "Print the current version" — version --help: "Show the installed version of the gh aw extension."

L3 — --days constraint notation inconsistent (forecast vs health)

forecast: (allowed values: 7, 30) — health: (7, 30, or 90)

L4 — --stdin "instead of..." clause differs (logs vs audit)

logs: "...instead of discovering runs via the GitHub API"
audit: "...instead of positional arguments"

L5 — --no-merge name misleads

Actual behavior is "override local with upstream," not just "don't merge."
Consider --force-upstream or --override-local.

L6 — --cache-before sole flag description ending with a period (306 others do not)

L7 — secrets bootstrap short aliases missing from docs options list

CLI has -e, --engine and -r, --repo; docs list only the long forms.

---

Inspection Metadata

Item	Value
Date	2026-06-22
Commands inspected	34 subcommands + root
Total flags analyzed	307
Docs file	docs/src/content/docs/setup/cli.md
Workflow run	27962283169

Generated by ✅ CLI Consistency Checker · 391.7 AIC · ⌖ 11.4 AIC · ⊞ 4.2K · ◷

• expires on Jun 24, 2026, 7:21 AM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-06-24T15:21:08.229Z.

Closed by Workflow