Repository navigation
[cli-consistency] CLI Consistency Issues - 2026-05-28 #35489
Description
Automated CLI consistency inspection run on 2026-05-28 against /tmp/gh-aw/agent/all-help-collected.txt and docs/src/content/docs/setup/cli.md.
Commands inspected: add, add-wizard, deploy, env, init, new, remove, secrets, update, upgrade, compile, domains, fix, lint, mcp, validate, disable, enable, run, trial, audit, checks, forecast, health, list, logs, status, completion, hash-frontmatter, mcp-server, pr, project, outcomes, version (34 commands)
Summary: 3 high · 6 medium · 10 low severity issues across 3 categories.
Severity Breakdown
| Severity | Count | Category |
|---|---|---|
| 🔴 High | 3 | Docs: missing commands / missing flags |
| 🟡 Medium | 6 | Flag naming / negation inconsistencies |
| 🟢 Low | 10 | Grammar, punctuation, terminology in help text |
🔴 High — Documentation Gaps
Missing Commands in Docs
gh aw forecast — entirely absent from docs
- Affected:
docs/src/content/docs/setup/cli.md - The
[EXPERIMENTAL]forecastcommand is fully implemented with 6 flags (--days,--eval,--json/-j,--period,--repo/-r,--sample) but has no documentation entry. - Fix: Add a
#### forecastsection (e.g., under Monitoring or Advanced), note experimental status, document all flags.
gh aw env — entirely absent from docs
- Affected:
docs/src/content/docs/setup/cli.md - The
envcommand (manages compiler defaults for repo/org/enterprise scope) with subcommandsenv getandenv updateis missing entirely. - Fix: Add a
#### envsection documenting both subcommands and their flags.
Missing Global Flag
--banner missing from Global Options table
- Docs list only
--helpand--verbosein the Global Options table. - Help output:
--banner Display ASCII logo banner with purple GitHub color theme(appears on every command). - Fix: Add
--bannerrow to the Global Options table.
Missing Flags on Existing Commands
4 flags missing from documented commands
| Command | Missing Flag | Help Description |
|---|---|---|
compile |
--ghes |
Enable GitHub Enterprise Server (GHES) compatibility mode |
compile |
--show-all |
Display all prioritized compilation errors instead of the default top five |
compile |
--staged |
Force all safe-outputs into staged mode |
upgrade |
--pre-releases |
Include pre-release versions when checking for extension upgrades |
update |
--disable-security-scanner |
Disable security scanning of workflow markdown content |
trial |
--json/-j |
Output results in JSON format |
Fix: Add each flag with its description to the respective command's Options section in the docs.
🟡 Medium — Flag Naming & Negation Inconsistencies
6 flag consistency issues
Inconsistent Short Forms
--force short form -f missing on compile
add,deploy,new,updateall expose-f, --forcecompileexposes--forcewithout-f- Fix: Add
-fto--forceingh aw compile.
--logical-repo short form -l missing on compile
trial:-l, --logical-repo stringcompile:--logical-repo string(no-l)- Fix: Add
-lto--logical-repoingh aw compile.
Confusing --no-X Negation Pairs Across Commands
--fix / --no-fix split across different commands
compile --fix= opt-in positive flagupgrade --no-fix= standalone skip flag (no--fixonupgrade)- Fix: Either add a default-on
--fixtoupgrade(with--no-fixas its negation), or rename to--skip-fix/--skip-codemodsto clarify it is independent.
--staged / --no-staged split across different commands
compile --staged= opt-in positive flaglogs --no-staged= filter flag (no positive--stagedcounterpart)- Fix: Rename
logs --no-stagedto--exclude-stagedto avoid implying it negatescompile's--staged.
--firewall / --no-firewall both as explicit filter flags on logs
- Both flags exist on
gh aw logsas mutually exclusive filters. Standard--no-Xconvention means "disable default-on behaviour," not "a second explicit filter." - Fix: Replace with
--firewall=<enabled|disabled|all>or rename to--with-firewall/--without-firewall.
--no-X Flags With No Positive Counterpart
The following --no-X flags have no corresponding --X anywhere. This is a valid pattern for disabling defaults but is inconsistently applied alongside positive opt-in flags elsewhere:
| Flag | Command |
|---|---|
--no-actions |
upgrade |
--no-check-update |
compile, validate |
--no-compile |
update, upgrade |
--no-emit |
compile |
--no-gitattributes |
add, add-wizard, deploy |
--no-mcp |
init |
--no-merge |
update |
--no-redirect |
update |
Fix: Adopt a consistent convention — prefer --no-X for skipping default-on behaviour, and audit opt-in positive flags (like --fix, --staged) to confirm they follow the same pattern.
🟢 Low — Grammar, Punctuation & Terminology in Help Text
10 help text issues
Missing comma after "e.g." (5 occurrences)
Standard English requires a comma after "e.g." in all cases.
| Command | Quoted Text | Fix |
|---|---|---|
deploy, update |
(e.g. 7d, 24h, 0 to disable) |
(e.g., 7d, 24h, 0 to disable) |
env |
(e.g. default_max_turns) |
(e.g., default_max_turns) |
compile (--schedule-seed) |
(e.g. "github/gh-aw") |
(e.g., "github/gh-aw") |
domains |
(e.g. "node", "python", "github") |
(e.g., "node", "python", "github") |
Grammar Issues
gh aw audit — dangling subject
- Quoted:
"When a single run is provided, generates a detailed Markdown report for that run." - Fix:
"When a single run is provided, the command generates a detailed Markdown report for that run."
gh aw pr — sentence fragment
- Quoted:
"Useful for migrating work from trial repositories to production repositories." - Fix:
"This is useful for migrating work from trial repositories to production repositories."
compile / validate --strict — broken parallel list
- Quoted:
"(enforces action pinning, network config, safe-outputs, refuses write permissions and deprecated fields)" - Fix:
"(enforces action pinning, network config, and safe-outputs; refuses write permissions and deprecated fields)"
gh aw init — missing articles (3 occurrences)
| Quoted Text | Fix |
|---|---|
"if any workflows use expires field" |
"if any workflows use the expires field" |
"Configures permissions for current repo" |
"Configures permissions for the current repo" |
"Configures permissions for additional repos (in same org)" |
"Configures permissions for additional repos (in the same org)" |
Terminology Inconsistency
gh aw upgrade --pre-releases — mixed spelling
- Flag name:
--pre-releases(hyphenated) - Description mixes:
"pre-release versions"and"prereleases"in the same sentence - Quoted:
"Include pre-release versions when checking for extension upgrades; prereleases are installed by exact tag" - Fix:
"Include pre-release versions when checking for extension upgrades; pre-release versions are installed using their exact tag"
Inspection method: automated agents (typo-grammar-extractor, flag-consistency-analyzer, docs-vs-help-comparer) against live CLI output and docs.
Generated by ✅ CLI Consistency Checker · sonnet46 5M · ◷
- expires on May 30, 2026, 2:30 PM UTC
Activity
github-actions commentedon May 28, 2026
🍪 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! 🍪