Skip to content

[cli-consistency] CLI Consistency Issues - 2026-05-27Β #35223

@github-actions

Description

@github-actions

Automated CLI consistency inspection of gh aw β€” 26 commands analyzed on 2026-05-27.

Total issues: 26 | πŸ”΄ High: 8 | 🟑 Medium: 13 | 🟒 Low: 5


Severity Breakdown

Severity Count Categories
πŸ”΄ High 8 Missing flag short forms, naming conflicts, docs rename, undocumented command
🟑 Medium 13 Missing flags in docs, negation style inconsistencies, inverted defaults
🟒 Low 5 Typos, grammar, capitalization

### πŸ“– Docs vs CLI Help Mismatches (7 issues)

πŸ”΄ gh aw forecast β€” Entire command undocumented

The forecast command is completely missing from docs/src/content/docs/setup/cli.md.

CLI help text:

[EXPERIMENTAL] Forecast effective token usage for agentic workflows by sampling recent run history and projecting forward on a per-week or per-month basis.

Flags: --days, --eval, --json/-j, --period, --repo/-r, --sample

Fix: Add a new #### forecast section to cli.md with description, all six flags, and examples.


πŸ”΄ gh aw logs β€” --after flag renamed to --cache-before

Docs text: References --after flag throughout including heading, prose, Options list, and code examples:

gh aw logs --after -1w, gh aw logs --after -30d, gh aw logs --after 2024-01-01

CLI help text:

--cache-before string (Cache eviction) Evict locally cached run folders for runs before this date, prior to downloading.

Fix: Rename every occurrence of --after in docs to --cache-before; update the description.


🟑 gh aw compile β€” Missing flags --ghes, --show-all, --staged

CLI exposes these flags not documented in cli.md:

  • --ghes β€” Enable GitHub Enterprise Server compatibility mode
  • --show-all β€” Display all prioritized compilation errors instead of the default top five
  • --staged β€” Force all safe-outputs into staged mode

Fix: Add all three to the compile Options list in docs.


🟑 gh aw upgrade β€” Missing --pre-releases flag

CLI help text:

--pre-releases Include pre-release versions when checking for extension upgrades; prereleases are installed by exact tag

Fix: Add --pre-releases to the upgrade Options list in docs.


🟑 gh aw trial β€” Missing --json/-j flag

CLI help text:

-j, --json Output results in JSON format

Fix: Add -j, --json to the trial Options list in docs.


🟑 gh aw update β€” Missing --disable-security-scanner flag

CLI help text:

--disable-security-scanner Disable security scanning of workflow markdown content

Fix: Add --disable-security-scanner to the update Options list in docs.


🟑 gh aw audit β€” Missing flags --artifacts, --experiment, --output/-o, --variant

CLI help text:

  • --artifacts strings β€” Artifact sets to download (default: all)
  • --experiment string β€” Filter to runs that include this experiment name
  • -o, --output string β€” Output directory for generated files
  • --variant string β€” Filter to runs with a specific variant value

Fix: Add --artifacts and -o/--output to single-run audit Options; add --experiment and --variant to multi-run diff Options.


### 🚩 Flag Naming & Consistency Issues (12 issues)

πŸ”΄ --force missing -f short flag on gh aw compile

All sibling commands expose -f as the short form of --force, but gh aw compile does not.

Command Flag definition
gh aw add -f, --force Overwrite existing workflow files without confirmation
gh aw deploy -f, --force Overwrite existing workflow files without confirmation
gh aw new -f, --force Overwrite existing files without confirmation
gh aw update -f, --force Force update even if no changes are detected
gh aw compile --force Force overwrite of existing dependency files ← no -f

Fix: Add -f to --force in gh aw compile.


πŸ”΄ --logical-repo missing -l short flag on gh aw compile

gh aw trial defines -l, --logical-repo, but gh aw compile omits the short alias even though it uses the same flag.

Fix: Add -l to --logical-repo in gh aw compile.


πŸ”΄ --approve vs --yes β€” two flags for skip-confirmation

gh aw upgrade, gh aw compile, and gh aw run use --approve; gh aw trial uses --yes/-y. Both suppress confirmation but have different names.

Fix: Standardise on --approve across all commands; add -y as short form consistent with --yes -y in gh aw trial.


πŸ”΄ --dry-run vs --no-emit β€” two names for validate-only mode

Command Flag
gh aw run --dry-run Validate workflow without actually triggering execution
gh aw trial --dry-run Show what would be done without making any changes
gh aw compile --no-emit Validate workflow without generating lock files

Fix: Rename --no-emit β†’ --dry-run in gh aw compile.


πŸ”΄ --disable-* vs --no-* negation style inconsistency

The vast majority of opt-out flags use --no-*. Two flags break this pattern:

  • --disable-security-scanner (on gh aw add, deploy, update, trial)
  • --disable-release-bump (on gh aw update)

Fix: Rename to --no-security-scanner and --no-release-bump.


πŸ”΄ --skip-secret lone --skip-* outlier on gh aw add-wizard

--skip-secret Skip the API secret prompt

--skip-* is used exactly once across the entire CLI. All comparable flags use --no-*.

Fix: Rename to --no-secret-prompt.


🟑 --count / --last redundant visible aliases in gh aw logs

--last is documented as an alias for --count but appears as a first-class flag. --count has -c; --last has no short form. This creates two flags with the same effect.

Fix: Make --last a hidden alias, or promote it as canonical and hide --count.


🟑 --write inverts --dry-run convention in gh aw fix

--write Write changes to files (without this flag, no changes are made)

Across the CLI, --dry-run opts out of side effects (default is to act). In gh aw fix, the default is to not act and --write opts in. This is the inverse.

Fix: Rename --write β†’ --apply; consider adding --dry-run for consistency.


🟑 --approve has no short flag on three commands

--yes has -y in gh aw trial. --approve on gh aw upgrade, gh aw compile, and gh aw run has no short form.

Fix: Add -y as a short alias for --approve on those three commands.


🟑 --staged / --no-staged naming collision across different commands

Command Flag Purpose
gh aw compile --staged Force safe-outputs into staged mode
gh aw logs --no-staged Exclude workflow runs in staged mode

These are not a toggle pair β€” they're in different commands with different purposes. The naming collision is confusing.

Fix: Rename the gh aw logs filter flag to --exclude-staged to make it clearly a filter predicate.


🟑 --firewall / --no-firewall misuse --no-* toggle pattern

In gh aw logs, both --firewall and --no-firewall are filter flags (mutually exclusive values), not a boolean on/off toggle. The --no-* convention typically means "disable feature X", not "filter for absence of X".

Fix: Replace the two flags with --firewall=<bool> or --filter-firewall [enabled|disabled].


🟒 --format accepted values differ across commands without documentation

gh aw audit --format accepts pretty, markdown; gh aw logs --format accepts console, tsv, pretty, markdown. Both use --format but the value sets are different and undiscoverable without reading each help carefully.

Fix: Ensure help text for both commands explicitly lists all valid values.


### ✏️ Typos, Grammar & Capitalization Issues (7 issues)

🟒 gh aw deploy and gh aw update β€” Missing comma after "e.g."

Affected flag: --cool-down string

(e.g. 7d, 24h, 0 to disable)

Other flags in the same file correctly use (e.g., ...).

Fix: (e.g., 7d, 24h, 0 to disable)


🟒 gh aw upgrade β€” Inconsistent hyphenation of "pre-release"

The --pre-releases flag description uses three different forms:

  • prerelease (no hyphen)
  • pre-release (hyphenated)
  • prereleases (no hyphen, plural)

Fix: Standardize to pre-release / pre-releases throughout to match the flag name.


🟒 gh aw init β€” Missing article "the" in three places

  1. use expires field β†’ use the expires field
  2. for current repo: β†’ for the current repo:
  3. (in same org): β†’ (in the same org):

🟒 gh aw init β€” Broken parallel structure in "After running this command" list

Three bullets are imperative ("Use...", "Add...", "Create..."); one is declarative:

- The dispatcher will route your request to the appropriate specialized prompt

Fix: Rephrase as imperative: - Use the dispatcher to route your requests to the appropriate specialized prompt


🟒 gh aw mcp inspect β€” "MCP Scripts" capitalization inconsistency

Same concept referred to as:

  • MCP Scripts servers (title-case)
  • mcp-scripts server (lowercase kebab-case)

Fix: Standardize to lowercase mcp-scripts to match the configuration key used in workflows.


Inspection Metadata

Field Value
Commands inspected 26 (including subcommands)
Date 2026-05-27
Source /tmp/gh-aw/agent/all-help.txt (live --help output)
Doc compared docs/src/content/docs/setup/cli.md
Workflow run 26516684258
Method Automated: typo-grammar-extractor, docs-vs-help-comparer, flag-consistency-analyzer

Generated by βœ… CLI Consistency Checker Β· sonnet46 5.5M Β· β—·

  • expires on May 29, 2026, 2:25 PM UTC

Metadata

Metadata

Labels

automationclicookieIssue Monster Loves Cookies!documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions