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

[github-actions]

Summary

Comprehensive CLI consistency inspection performed on 2026-07-13. The inspection covered all 28 top-level commands and their flags, compared help text against docs/src/content/docs/setup/cli.md, and analyzed flag naming across the full CLI.

Severity	Count
🔴 High	1
🔴 Medium	11
🟡 Low	26
Total	38

---

Category 1: Grammar, Typos & Style

16 findings — grammar, capitalization, punctuation, awkward phrasing

G-1 · Medium · Missing "the" — add, add-wizard, deploy, trial

Exact text: "Append extra content to the end of agentic workflow on installation"
Expected: "Append extra content to the end of **the** agentic workflow on installation"
Affected flags: --append on add, add-wizard, deploy, trial

---

G-2 · Low · Mixed parallel structure — deploy

Exact text: "by combining clone, update, add, compile, and pull request creation"
Expected: "by combining cloning, updating, adding, compiling, and creating a pull request" (all gerunds)

---

G-3 · Low · Non-idiomatic "in batch" — env

Exact text: "Manage compiler default variables in batch for repository, organization, or enterprise scope."
Expected: "...in bulk for repository..." — "in batch" is non-idiomatic; standard English is "in bulk"

---

G-4 · Low · Missing article "a" — env

Exact text: "in batch for repository, organization, or enterprise scope"
Expected: "for a repository, organization, or enterprise scope"

---

G-5 · Low · Missing "the" — init

Exact text: "if any workflows use expires field for discussions or issues"
Expected: "if any workflows use **the** expires field for discussions or issues"

---

G-6 · Medium · Capitalization — new

Exact text: "- Tools configuration (github, claude, MCPs)"
Expected: "- Tools configuration (GitHub, Claude, MCPs)" — github and claude are proper names

---

G-7 · Low · Abbreviation inconsistency — trial

Exact text: "(github.repository context points to current repo)"
Expected: "...points to the current **repository**)" — "repo" is abbreviated inconsistently with surrounding text

---

G-8 · Low · Missing "the" — trial

Exact text: "Trial results are saved both locally (in trials/ directory) and..."
Expected: "(in **the** trials/ directory)"

---

G-9 · Low · Missing comma after introductory phrase — logs

Exact text: "By default only the compact usage artifact is downloaded..."
Expected: "By default**,** only the compact usage artifact..."

---

G-10 · Low · Missing "a" — health

Exact text: "- Success/failure rates over time period"
Expected: "...over **a** time period"

---

G-11 · Low · Sentence fragment — pr

Exact text: "Useful for migrating work from trial repositories to production repositories."
Expected: "**This is** useful for migrating..." — has no grammatical subject

---

G-12 · Low · Redundant "specific...specified" — compile

Exact text: "(only when no specific files are specified)"
Expected: "(only when no specific files are **provided**)"

---

G-13 · Low · Missing article — mcp

Exact text: "# Inspect MCP servers in workflow"
Expected: "# Inspect MCP servers in **a** workflow"

---

G-14 · Low · Plural/singular adjective — init

Exact text: "with agentic workflows support" (--codespaces description)
Expected: "with agentic workflow support" — "workflow" used as adjective modifier should be singular (consistent with "agentic workflow files" etc.)

---

G-15 · Low · Ambiguous numbered list structure — fix

The numbered list (steps 1–3 then "additionally" steps 4–7) splits across two prose sections, making the continuation unclear. The "additionally: 4." numbering is confusing.
Suggested fix: Start a new numbered list for the --write steps rather than continuing the global sequence.

---

G-16 · Low · Flag name vs description inconsistency — deploy, update

Exact text: Flag is --cool-down (hyphenated) but description says "Cooldown period" (unhyphenated)
Suggested fix: Use consistent form in description: "Cool-down period" to match flag name, or rename flag to --cooldown.

---

Category 2: Docs vs. CLI Help Mismatches

13 findings — documentation differs from actual CLI

D-1 · Medium · health --days allowed values undocumented

Docs say: Examples show --days 30 and --days 90, no restriction noted.
CLI help says: "Number of days to analyze (7, 30, or 90) (default 7)"
Impact: Users passing --days 14 or --days 60 will get an error with no docs warning.

---

D-2 · Medium · secrets set / secrets bootstrap sub-command flags unverifiable

Help for gh aw secrets set and gh aw secrets bootstrap was not included in the pre-collected help. Docs document --value, --value-from-env, --api-url for set and --engine, --non-interactive, --repo for bootstrap. These cannot be verified.
Suggested fix: Ensure secrets set --help and secrets bootstrap --help are collected in CI.

---

D-3 · Medium · env get / env update sub-command flags unverifiable

Same issue as D-2 for gh aw env get and gh aw env update. Docs document --scope, --org, --enterprise, --yes/-y, --dry-run but CLI sub-command help was not captured.

---

D-4 · Medium · update --cool-down default (7d) not mentioned in docs

Docs say: No mention of default cool-down value for update.
CLI help says: --cool-down string ... (default "7d")
The deploy section in docs does state the 7d default, but update docs do not.

---

D-5 · Medium · update — numerous CLI examples absent from docs

CLI has 13 documented examples for update; docs show only 8. Missing from docs: --cool-down 0, --cool-down 3d, --no-redirect, --no-compile, and several --org mode variants.

---

D-6 · Low · update --no-release-bump description framing differs

Docs say: "Use --no-release-bump to restrict force-updates to core actions/* actions only."
CLI example comment says: "# Disable force-bumping non-core actions (core actions/* are still force-updated)"
Same meaning, opposite framing. Docs could align with CLI example for clarity.

---

D-7 · Low · forecast --sample default not in docs

CLI help says: --sample int ... (default 100). Docs show example --sample 50 but never state the default.

---

D-8 · Low · trial — results saved to host repo not mentioned in docs

Docs say (short form): "Results saved to trials/."
CLI help says: "Trial results are saved both locally (in trials/ directory) and in the host repository for future reference."

---

D-9 · Low · init --no-mcp description less specific in docs

Docs/example comment: "# Skip MCP server integration"
CLI help: "--no-mcp Skip configuring gh-aw MCP server integration for GitHub Copilot Agent" — docs omit scope ("for GitHub Copilot Agent").

---

D-10 · Low · status — stop-after expiration not mentioned in docs

CLI help: "Displays...time remaining until expiration (if stop-after is configured)"
Docs: Do not mention the expiration column or stop-after in the status section.

---

D-11 · Low · mcp inspect auto-detection claim in docs not reflected in CLI

Docs say: "mcp inspect auto-detects mcp-scripts."
CLI help: No mention of mcp-scripts auto-detection in mcp help text.

---

D-12 · Low · upgrade — 8 CLI examples absent from docs

CLI has examples for --no-actions, --no-compile, --dir, --pre-releases, and all --org mode variants. Docs show only 5 examples, all of which are in CLI.

---

D-13 · Low · logs caching claim "10-100x speedup" in docs not in CLI help

Docs say: "Results cached for 10-100x speedup on subsequent runs."
CLI help: No mention of caching or speedup in description.

---

Category 3: Flag Consistency

13 findings — naming, negation style, short flags, descriptions

F-1 · 🔴 High · --staged / --no-staged split across unrelated commands

Command	Flag	Meaning
gh aw compile	--staged	Force all safe-outputs into staged mode (compilation setting)
gh aw logs	--no-staged	Filter out runs that ran in staged mode (query filter)

Impact: Users encountering --no-staged on logs expect a --staged filter there too; --staged on compile has no --no-staged toggle. These are semantically unrelated flags sharing the same base name.
Suggested fix: Rename the logs filter to --exclude-staged or --staged-only.

---

F-2 · Medium · --yes missing org-mode/CI context on trial

Command	--yes description
deploy, update, upgrade	"Auto-accept org-mode ... confirmations (required in CI)"
trial	"Skip confirmation prompts"

trial --yes is described generically; inconsistent with the explicit CI/org-mode framing on other commands.

---

F-3 · Medium · -e short flag missing on gh aw logs --engine

Every other command with --engine provides -e as a short form. gh aw logs --engine omits -e, breaking muscle memory.

---

F-4 · Medium · --timeout three different "0 = no timeout" phrasings

Command	Phrasing
trial	"(set to 0 to disable timeout)"
forecast	"(0 disables timeout)"
logs	"(0 = no timeout)"

Suggested fix: Standardize to "(0 = no timeout) (default N)" across all three.

---

F-5 · Medium · --output vs --outcomes-dir on same command (outcomes)

gh aw outcomes has both -o, --output string ("Output directory for generated files") and --outcomes-dir string ("Write outcome JSONL to this directory for OTLP export"). The second is the only --<noun>-dir pattern in the entire CLI. Confusing dual directory flags.
Suggested fix: Rename --outcomes-dir to --otlp-dir.

---

F-6 · Medium · --force different semantics across 5 commands

Command	--force meaning
add, deploy, new	Overwrite existing files without confirmation
update	Force re-run even if no changes detected
compile	Force overwrite of dependabot.yml only (only meaningful with --dependabot)

compile's narrow scope for --force (only dependabot.yml) is surprising given the flag's meaning elsewhere.

---

F-7 · Medium · --format different accepted values on audit vs logs

Command	Accepted values
audit	pretty, markdown
logs	console, tsv, pretty, markdown

--format console on audit will error. Docs for audit should list its accepted values explicitly.

---

F-8 · Medium · --repo required on deploy but no (required) marker shown

On all commands --repo defaults to current repo. On deploy it is required unless --org is given. Description says so but no (required) marker in the flag listing — users may only discover this at runtime.

---

F-9 · Low · --firewall / --no-firewall unique dual-filter pattern on logs

The --firewall / --no-firewall pair on logs is the only command using both positive and negative forms as peer query filters. All other --no-* flags in the CLI are opt-out toggles for defaults. This breaks the mental model.

---

F-10 · Low · --last is a hidden alias for --count only on logs

gh aw logs --last int describes itself as "Alias for --count/-c". No other command has such self-describing aliases. Adds confusion without adding value.

---

F-11 · Low · --logical-repo description omits default on compile

Command	Description
compile	"Repository to simulate workflow execution against (for trial mode)"
trial	"Repository to simulate workflow execution against, as if the workflow was installed there (defaults to current repository)"

compile omits the default and the fuller explanation.

---

F-12 · Low · --dry-run non-parallel descriptions on run vs trial

Command	Description
run	"Preview workflow execution without triggering runs on GitHub Actions"
trial	"Preview trial execution without creating repos or running workflows"

Both follow "Preview X without Y" but word choices differ enough to feel unrelated.

---

F-13 · Low · -F uppercase short flag for --raw-field on run

-F is unconventional (all other short flags are lowercase). This intentionally mirrors gh CLI conventions but is worth noting for users unfamiliar with gh.

---

Inspection Metadata

Item	Value
Date	2026-07-13
Commands inspected	28 top-level commands + subcommands
Source of truth	/tmp/gh-aw/agent/all-help.txt + docs/src/content/docs/setup/cli.md
Method	Automated help collection + multi-agent analysis
Workflow run	29255177404

Patterns Observed

1. Missing articles ("the", "a") are the most common grammar issue — appears 5+ times
2. Subcommand help not captured: secrets and env have undocumented subcommand flags in docs that couldn't be verified
3. logs flag outlier: gh aw logs has the most flag inconsistencies (missing -e, --no-staged naming, --last alias, --firewall dual-filter)
4. Examples coverage gap: update and upgrade have many CLI examples not reflected in docs
5. --force semantic drift: The flag has accumulated 3 different meanings across commands

Warning

Firewall blocked 1 domain

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

• proxy.golang.org

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

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · 245 AIC · ⌖ 8.32 AIC · ⊞ 4.4K · ◷

• expires on Jul 15, 2026, 6:01 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! 🍪

🍪 Om nom nom by Issue Monster · 1.37 AIC · ⌖ 11.3 AIC · ⊞ 8.6K · ◷