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

[github-actions]

Summary

Comprehensive inspection of the gh-aw CLI help output and documentation performed on 2026-07-22.

• Commands inspected: 25+ subcommands
• Total issues found: 30
• Severity breakdown: 7 medium · 23 low
• Method: CLI help collected via ./gh-aw <cmd> --help, compared with docs/src/content/docs/setup/cli.md

Severity Legend

• 🟡 medium — noticeably confusing, incomplete engine lists, misleading flag names
• 🟢 low — style, punctuation, missing detail

---

A — Typos, Grammar, Capitalization, Punctuation (9 issues)

A-1 · add-wizard and completion list only 4 of 7 engines — Medium

add-wizard description:

"Selecting an AI engine (Copilot, Claude, Codex, or Gemini)"

completion bullet:

"Engine name completion for --engine flag (copilot, claude, codex, gemini)"

The --engine flag on every command lists 7 engines: copilot, claude, codex, gemini, antigravity, opencode, pi. Both descriptions silently omit three.

Fix: Update both to list all 7 engines.

---

A-3 · fix numbered list: inconsistent verb form — Low

Items 1–3 use implied third-person verbs while the lead-in says "the command performs". Item 4 uses the imperative "Write updated files back to disk." instead of third-person "Writes ...".

Fix: Use third-person singular verbs throughout: "Writes updated files back to disk."

---

A-4 · trial description: unnecessary scare-quotes — Low

"without making actual changes to the "simulated" host repository."

The word simulated appears unquoted three other times in the same paragraph.

Fix: Remove quotes: without making actual changes to the simulated host repository.

---

A-6 · init flags: inconsistent casing of "Agentic Workflows" — Low

• --no-agent: "Skip creating the Agentic Workflows custom agent"
• --no-skill: "Skip creating the agentic-workflows dispatcher skill"

Both artifact paths use agentic-workflows (lowercase/hyphenated). The descriptions should match.

---

A-7 · logs vs audit --artifacts default description style — Low

• logs: (default: usage — compact summary for faster downloads) (em-dash)
• audit: (default: all, because auditing requires comprehensive artifacts for analysis) (comma)

Inconsistent style for the same type of parenthetical default description.

---

A-8 · deploy description: mixed noun/verb list — Low

"by combining clone, update, add, compile, and pull request creation"

First four items are bare verbs; fifth is a full noun phrase.

Fix: "by cloning the target repository, updating existing workflows, adding specified workflows, compiling lock files, and opening a pull request."

---

A-9 · mcp-server description: dangling participle — Low

"This command starts an MCP server that wraps the gh aw CLI, spawning subprocess calls for each tool invocation."

"spawning" dangles from the wrong subject.

Fix: "This command starts an MCP server that wraps the gh aw CLI. It spawns a subprocess for each tool invocation to ensure that GitHub tokens and other secrets are not shared with the MCP server process itself."

---

B — Flag Naming and Negation Style Inconsistencies (6 issues)

B-1 · fix --write vs --dry-run pattern inconsistency — Medium

Command	Default	Flag to change
fix	dry-run	--write (enable writes)
trial	create repos	--dry-run (disable)
env update	live update	--dry-run (disable)

The fix command uses a positive flag (--write) to escape dry-run mode, while trial/env update use --dry-run to enter it.

---

B-2 · --no-release-bump name is misleading — Medium

"Disable automatic major version bumps for all actions (only core actions/* are force-updated)"

The flag still force-bumps core actions/*, so it restricts bumps rather than disabling them. The flag name implies complete disabling.

Fix: Update description to: "Restrict automatic major version bumps to core actions/* only (non-core actions are left as-is)"

---

B-3 · --yes description differs on trial vs org-mode commands — Low

trial --yes: "Auto-accept trial confirmations (required in CI)" vs. update/upgrade/deploy: "Auto-accept org-mode confirmations (required in CI)"

---

B-4 · compile --force scope undocumented in flag description — Medium

compile --force only applies when --dependabot is also set, but the flag description doesn't state this.

Fix: "Force overwrite of existing dependency files (only applies when --dependabot is set; e.g., dependabot.yml)"

---

B-5 · deploy always creates a PR but doesn't explain absence of --create-pull-request — Medium

deploy opens a PR by design, unlike add/update/upgrade/init which use --create-pull-request optionally. The help never explains that PR creation is mandatory.

Fix in help: "This command always creates a pull request; the --create-pull-request flag is not needed."

---

B-6 · --approve on run has narrower scope but description doesn't clarify — Low

run --approve only applies when --push triggers a recompile step, unlike the broader --approve on compile/update/upgrade.

---

C — Docs vs Help Mismatches (9 issues)

C-1 · gh aw version --help absent from captured help output — Medium

The docs reference gh aw version with a full section but the command was not captured in pre-collected help. Verify gh aw version --help outputs usable help text.

---

C-2 · secrets bootstrap --engine list in docs is incomplete — Medium

cli.md: --engine (copilot, claude, codex, gemini) — missing antigravity, opencode, pi.

Fix in docs: Update to list all 7 engines.

---

C-3 · health --days valid values not stated in docs — Low

The forecast --days docs warn "accepts only 7 or 30". The health --days docs don't state valid values (7, 30, or 90).

Fix: Add: "The --days flag accepts 7, 30, or 90 (default: 7)."

---

C-5 · run --approve docs lack --push context — Low

Docs list --approve in run options without explaining it only matters when --push triggers a recompile.

---

C-6 · logs --report-file, --summary-file absent from docs options list — Low

Both flags are in help but not in the **Options:** summary at cli.md line 506.

---

C-7 · logs --tool-graph, --train absent from docs options list — Low

Both flags appear in narrative text but not the **Options:** summary.

---

C-8 · audit --evals absent from docs options list — Low

--evals is in help but not in docs options at cli.md line 535.

---

C-11 · mcp-server --validate-actor missing key detail in docs — Low

Docs: "enforce actor validation for logs and audit tools"
Help: "Enforce actor validation (logs/audit tools return errors without GITHUB_ACTOR)"

The critical consequence is missing from docs.

---

C-12 · Docs --push section omits --approve interaction — Low

The --push section doesn't mention that --approve may be needed when --push triggers auto-recompile in strict mode.

---

D — Example Correctness (6 issues)

D-1 · add example comment incorrectly identifies spec type — Medium

gh aw add githubnext/agentics/repo-assist  # Add package from repository root aw.yml

githubnext/agentics/repo-assist is a three-part spec that looks in workflows/ — NOT the root aw.yml. The root aw.yml is loaded by the two-part spec githubnext/agentics.

Fix: Change comment to # Add workflow from workflows/ directory or use gh aw add githubnext/agentics # Add package from repository root aw.yml.

---

D-2 · --repeat 3 = 4 total runs: counter-intuitive — Low

gh aw run daily-perf-improver --repeat 3  # Run 4 times total (1 initial + 3 repeats)

Flag description should add: "Note: --repeat 0 (default) runs once; --repeat 1 runs twice total."

---

D-4 · audit bare numeric ID example lacks --repo — Medium

gh aw audit 1234567890  # Audit run with ID 1234567890

The flag description says --repo is required for bare numeric IDs. The example should show this.

Fix: gh aw audit 1234567890 --repo owner/repo # Audit with bare run ID (--repo required)

---

D-5 · logs --cache-before comment implies filtering behavior — Low

gh aw logs --cache-before -1w  # Clean folders older than 1 week, then download latest runs

--cache-before only evicts local cache; it doesn't filter which runs are fetched.

Fix: # Evict local cache older than 1 week, then proceed with normal run download

---

D-7 · init --engine claude comment is cryptic — Low

gh aw init --engine claude  # Skip Copilot-specific artifacts

Fix: # Use Claude engine — skips Copilot MCP/skill files

---

Inspection Metadata

Field	Value
Date	2026-07-22
Commands inspected	25+ subcommands
Source of truth	./gh-aw <cmd> --help output
Docs compared	docs/src/content/docs/setup/cli.md
Workflow run	29925018585
Total findings	30
High severity	0
Medium severity	7
Low severity	23

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• releaseassets.githubusercontent.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "releaseassets.githubusercontent.com"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · sonnet46 148.1 AIC · ⌖ 13.6 AIC · ⊞ 4.6K · ◷

• expires on Jul 24, 2026, 5:57 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

I have 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 · gpt54 2.69 AIC · ⌖ 7.91 AIC · ⊞ 7.7K · ◷