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

[github-actions]

Summary

Comprehensive CLI inspection of gh-aw found 18 issues (2 high, 6 medium, 10 low).

Severity	Count
🔴 High	2
🟡 Medium	6
🔵 Low	10

Commands inspected: 34 | Date: 2026-06-12 | Run: 27420894190

---

🔴 High

H1 — outcomes command in wrong CLI group (code bug)

outcomes appears under Additional Commands instead of Analysis Commands in gh aw --help. Root cause: outcomesCmd.GroupID = "analysis" is missing in cmd/gh-aw/main.go. Every other analysis command has this assignment; outcomesCmd does not.

Fix: Add outcomesCmd.GroupID = "analysis" near line 838–844 in main.go.

---

H2 — remove docs say "prefix" but CLI implements substring matching

CLI help (correct):

You can provide a substring to match multiple workflows
gh aw remove test-   # Remove all workflows containing 'test-' in name

Docs (wrong):

Accepts a workflow ID (basename without .md) or prefix pattern.
gh aw remove test-  # Remove all workflows starting with 'test-'

Fix: Update docs — replace "prefix pattern" → "substring pattern" and "starting with" → "containing".

---

🟡 Medium

6 medium findings

M1 — fix docs missing --disable-codemod flag

CLI has --disable-codemod strings Disable specific codemod IDs (repeatable) but docs Options list only shows --dir/-d, --list-codemods, --write.

M2 — upgrade docs missing --disable-codemod flag

CLI has --disable-codemod strings Disable specific codemod IDs during the fix step (repeatable) but docs Options list omits it.

M3 — compile --force missing -f short alias

Every other command with --force exposes -f (add, new, update, deploy). compile uniquely omits it:

      --force   Force overwrite of existing dependency files  # no -f

M4 — list --path vs --dir for remote directories

list uses --path for remote repo directory (--path only works with --repo), while every other command reuses --dir for both local and remote. Users must learn a different flag name in list alone.

M5 — --approve missing from update and deploy

compile, run, and upgrade all expose --approve to bypass safe-update enforcement during recompilation. update and deploy trigger the same enforcement but offer no escape hatch.

M6 — Mixed --disable-xxx vs --no-xxx negation style

update mixes both styles in the same command:

      --disable-release-bump       Disable automatic major version bumps
      --disable-security-scanner   Disable security scanning
      --no-compile                 Skip recompiling workflows
      --no-merge                   Override local changes with upstream
      --no-stop-after              Remove any stop-after field

Same inconsistency in add, upgrade, deploy. Suggested convention: standardize on --no-xxx.

---

🔵 Low

10 low findings

L1 — forecast inconsistent experimental label

Main help: (experimental) — Command help: [EXPERIMENTAL]. Should be consistent.

L2 — project new docs omit -l alias for --link

CLI: -l, --link string — Docs only mention --link.

L3 — update missing --json/-j (but upgrade has it)

upgrade supports machine-readable JSON output; update does not despite doing equivalent work.

L4 — upgrade missing --engine/-e

upgrade internally calls compile but doesn't forward --engine to let users override the AI engine.

L5 — add-wizard missing flags present in add

add-wizard is missing --append, --disable-security-scanner, --force/-f, and --name/-n that add exposes.

L6 — compile --logical-repo missing -l short alias

trial -l/--logical-repo has a short alias; compile --logical-repo does not, despite the same concept.

L7 — outcomes --output missing default value

audit and logs show (default ".github/aw/logs") for their -o/--output. outcomes --output shows no default.

L8 — -e/--engine means "filter" in logs vs "override" elsewhere

In all 10+ commands, -e overrides the AI engine. In logs only, it filters historical runs. Same flag name, opposite semantic direction.

L9 — logs --last is a redundant alias for --count/-c

--last int Alias for --count adds confusion with no short form and no clear advantage over --count/-c.

L10 — trial --timeout doesn't document 0 = no timeout

logs and forecast both say (0 = no timeout). trial --timeout is silent on this behavior.

---

Method

• CLI help collected via ./gh-aw [cmd] --help for all 34 commands/subcommands
• Compared against docs/src/content/docs/setup/cli.md
• Code verified in cmd/gh-aw/main.go

Generated by ✅ CLI Consistency Checker · 1.3K AIC · ⌖ 13.4 AIC · ⊞ 15.8K · ◷

• expires on Jun 14, 2026, 6:22 AM UTC-08:00

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: Please try again later, or contact support if the problem persists. (Request id: 2000:3E3AE1:3B6D21:DBAFB2:6A2C9F61)

[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 · 40 AIC · ⌖ 12.7 AIC · ⊞ 24.4K · ◷