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

🔴 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.

🔴 --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.

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

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

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.

🟢 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.