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

[github-actions]

Summary

Comprehensive CLI consistency inspection conducted on 2026-07-20, covering all gh aw commands and comparing help text against docs/src/content/docs/setup/cli.md.

Total commands inspected: 24 (plus 9 missing from pre-collected help — see DM-1, DM-2)
Total issues found: 24

Severity	Count
🔴 High	1
🟡 Medium	6
🟢 Low	17

---

Typos & Grammar

ID	Severity	Location	Issue	Suggested Fix
TG-1	🟡 medium	trial help	"All workflows must support workflow_dispatch trigger" — missing article	"...support the workflow_dispatch trigger"
TG-2	🟢 low	trial help	"created as private and kept by default" — awkward phrasing	"created as a private repository and retained by default"
TG-3	🟡 medium	cli.md line 8	"natural language markdown files" — lowercase proper noun	"natural language Markdown files"
TG-4	🟢 low	checks help & docs	Status descriptions mix past tense ("passed", "failed") and present tense ("are blocking")	"policy_blocked - policy or account gates blocked the PR"

---

Flag Naming Inconsistencies

ID	Severity	Command	Issue	Suggested Fix
FN-1	🟡 medium	trial	--delete-host-repo-after vs --force-delete-host-repo-before — inconsistent verb ordering and prefix style	Standardize to --delete-host-repo-before / --delete-host-repo-after pair, separate --force if needed
FN-2	🟢 low	remove	--keep-orphans uses positive form; rest of CLI uses --no-* negation convention (e.g., --no-merge, --no-compile, --no-mcp)	Rename to --no-orphan-cleanup or --no-remove-orphans
FN-3	🟢 low	run	-F uppercase short flag breaks CLI-wide lowercase-only convention	Remove -F shorthand or document the exception

---

Docs vs Help Text Mismatches

DM-1 🔴 HIGH — Four commands in docs but entirely missing from help collection

The following commands appear in both cli.md and the root --help listing under "Analysis Commands", but had no --help output captured:

• forecast
• experiments
• outcomes
• health

If these commands exist in the binary, their --help output should be included in any automated help collection. If they are documented prematurely, the docs should be updated to reflect their availability.

DM-2 🟡 MEDIUM — Five utility commands in docs but missing from help collection

The following utility/advanced commands appear in docs and/or root help listing but had no --help entries captured:

• pr
• hash-frontmatter
• completion
• mcp-server
• project

Same remediation as DM-1.

ID	Severity	Command	Issue	Suggested Fix
DM-3	🟡 medium	doctor --repo	Description omits [HOST/] GHES prefix unlike every other --repo flag	"-r, --repo string Target repository ([HOST/]owner/repo format)"
DM-4	🟢 low	root help / logs	Root common tasks comment: "# View execution logs" but command downloads/analyzes	"# Download and analyze execution logs"
DM-5	🟢 low	cli.md line 344	"pinned Actions, no deprecated fields" — "Actions" capitalized as product name	"pinned actions, no deprecated fields"
DM-6	🟢 low	cli.md line 181	"from The Agentics collection" — spurious capital "The"	"from the Agentics collection"
DM-7	🟢 low	update help	Default action-bump behavior is documented in cli.md but not mentioned in update --help	Add note about default action pinning bump behavior to help text
TG-5	🟢 low	cli.md line 136	--push docs say "stages all changes"; help says "workflow files (including transitive imports)". Docs also mention "requires a clean working directory" which is absent from help	Reconcile both; add clean-directory requirement to help text

---

Inconsistent Flag Descriptions Across Commands

ID	Severity	Commands	Issue	Suggested Fix
ID-1	🟡 medium	logs, audit (--evals)	logs: "Filter to runs containing evals results" vs audit: "Skip runs that do not contain evals results" — opposite phrasings for same behavior	Standardize to positive phrasing: "Filter to runs containing evals results (evals.jsonl)"
ID-2	🟢 low	run --approve vs compile/update/upgrade --approve	run has a minimal one-line description; others have multi-sentence strict-mode explanation	Add cross-reference or expand run --approve to mention strict-mode behavior
ID-3	🟢 low	new --force vs add/deploy --force	new: "Overwrite existing files" vs add/deploy: "Overwrite existing workflow files"	new --force: "Overwrite existing workflow files without confirmation"

---

Style Inconsistencies

Style issues (7 low-severity items)

ID	Command	Issue	Suggested Fix
ST-1	upgrade help	"DEPENDENCY HEALTH AUDIT:" is the only ALL-CAPS section header in all help text	Use sentence case: "Dependency health audit:"
ST-2	fix help	Numbered list steps 4–7 continue across a prose break from steps 1–3, creating an awkward split	Reformat --write-specific steps as a separate labeled block
ST-3	logs help	Trailing period inconsistency in artifact set listings within the same command	Standardize punctuation at end of artifact set sentences
ST-4	logs help	"aw.patch: Git patch of changes made during execution (legacy; see aw-{branch}.patch)" — cross-reference style inconsistent with other deprecation notes	"aw.patch: Git patch of changes (deprecated; replaced by aw-{branch}.patch)"
ST-5	mcp, secrets help	Manual Available subcommands: bullet list duplicates cobra's Available Commands: table; env only has the cobra table	Remove manual bullet lists or standardize all parent commands to use the same style
ST-6	cli.md line 960	"Enable detailed debugging with namespace, message, and time diffs." — "time diffs" is informal	"Enable detailed debug logging showing namespace, log message, and elapsed time between logs."
TG-4	checks	Mixed tenses in check state list	Standardize to past tense throughout

---

Inspection Metadata

• Date: 2026-07-20
• Method: Binary help (gh-aw [command] --help) + docs file comparison
• Binary: /home/runner/work/gh-aw/gh-aw/gh-aw
• Docs file: docs/src/content/docs/setup/cli.md
• Commands with help captured: init, doctor, add-wizard, add, new, compile, list, run, status, logs, audit, deploy, env, remove, secrets, update, upgrade, domains, fix, lint, mcp, validate, disable, enable, trial, checks, version
• Commands in docs/root help but not in captured output: forecast, experiments, outcomes, health, pr, hash-frontmatter, completion, mcp-server, project

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• proxy.golang.org
• releaseassets.githubusercontent.com

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

network:
  allowed:
    - defaults
    - "proxy.golang.org"
    - "releaseassets.githubusercontent.com"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · 101.8 AIC · ⌖ 19.9 AIC · ⊞ 4.5K · ◷

• expires on Jul 22, 2026, 5:56 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! 🍪

Warning

Firewall blocked 1 domain

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

• pi.dev

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

network:
  allowed:
    - defaults
    - "pi.dev"

See Network Configuration for more information.

🍪 Om nom nom by Issue Monster · 1.31 AIC · ⌖ 5.36 AIC · ⊞ 7.6K · ◷