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

[github-actions]

Summary

Automated inspection of the gh aw CLI (--help output for all top-level and nested commands, cross-referenced with docs/src/content/docs/setup/cli.md) surfaced a small number of documentation and consistency issues. No typos or capitalization defects were found; the CLI text is generally clean. Most findings are low-to-medium severity naming/consistency and one medium documentation mismatch.

Severity breakdown:

• High: 0
• Medium: 2
• Low: 9

**Inspection meta(redacted)

• Commands inspected: all top-level commands (add, add-wizard, audit, checks, compile, completion, deploy, disable, doctor, domains, enable, env, experiments, fix, forecast, hash-frontmatter, health, init, lint, list, logs, mcp, mcp-server, new, outcomes, pr, project, remove, run, secrets, status, trial, update, upgrade, validate, version) plus nested subcommands (mcp add|inspect|list|list-tools, env get|update, secrets bootstrap|set, pr transfer, project new).
• Method: Built gh-aw from the pre-existing repo binary, ran --help on every command/subcommand, concatenated output, and analyzed it directly plus diffed against docs/src/content/docs/setup/cli.md.
• Date: 2026-07-28
• Run: 30364730143

---

Documentation Mismatches

1. [Medium] secrets bootstrap --engine supported values out of date in docs

   • Docs (cli.md): --engine/-e (copilot, claude, codex, gemini, antigravity, opencode, pi)
   • Actual CLI help: -e, --engine string Check tokens for specific engine (copilot, claude, codex, gemini)
   • Docs list 7 engines; CLI only supports 4 for this subcommand specifically.
   • Fix: Either update docs to match current CLI support, or (if newer engines should be supported) add them to secrets bootstrap's engine list in code.

2. [Low] secrets bootstrap docs description adds unverified claim

   • Docs say it "validates tokens before uploading to the repository"; the CLI's own long description doesn't mention token validation explicitly ("Analyze all workflows ... check which ones are already configured, and interactively prompt for any missing required secrets. Only required secrets are prompted for. Optional secrets are not shown.").
   • Fix: Confirm actual behavior and align docs wording with the CLI's stated behavior, or update the CLI help text to mention validation if it does occur.

---

Punctuation Inconsistency

3. [Low] Inconsistent trailing periods in flag descriptions
   • compile --ghes: "Enable GitHub Enterprise Server (GHES) compatibility mode. Artifact actions continue using latest non-v3 pins (v3 is deprecated). Overrides the aw.json ghes field" — first two sentences end with periods, the last does not.
   • General pattern: many single-clause flag descriptions across the CLI omit trailing periods (e.g., "Show help for gh aw add") while some multi-sentence descriptions end with a period after the last sentence (e.g., --cool-down: "...enabled. (default \"7d\")"), creating inconsistency.
   • Fix: Add the missing period to --ghes's description, and standardize the punctuation convention (either all flag descriptions end with a period, or none do) across the codebase.

---

Flag-naming and negation-style inconsistencies (9 findings) — click to expand

4. [Low] Two different flags express "skip confirmation": --force vs --yes

   • add, add-wizard, new: -f, --force Overwrite existing workflow files without confirmation
   • deploy, update, upgrade (org mode), trial, env update: -y, --yes Auto-accept ... confirmations (required in CI) / Skip confirmation prompt
   • deploy itself has both -f, --force (repo-mode) and -y, --yes (org-mode) depending on target mode.
   • compile --force means something unrelated: "Force overwrite of existing dependency files" for --dependabot.
   • Fix: Standardize on one flag (--yes or --force) for "skip confirmation"; reserve --force strictly for "overwrite existing files" semantics.

5. [Low] -l shorthand collision across unrelated flags

   • trial/compile --trial: -l, --logical-repo
   • project new: -l, --link
   • Same shorthand letter used for two unrelated concepts across different commands.
   • Fix: Reserve -l for one canonical meaning globally, or drop the shorthand for the less-common flag.

6. [Low] Two design patterns for "repo vs org" scope

   • deploy/update/upgrade: --org string + --repos strings (glob) alongside singular --repo.
   • secrets/env: --scope org|repo|ent enum.
   • Same underlying concept ("choose operation scope") modeled two different ways.
   • Fix: Adopt one consistent pattern (either --scope enum or --org/--repo flags) for all "repo vs org level" commands.

7. [Low] --verbose has special dual-purpose behavior only in logs

   • logs --json -v produces "Full JSON with audit metadata" vs plain --json "compact by default" — i.e. -v changes JSON payload content specifically in logs, whereas everywhere else --verbose is defined identically as "Enable verbose output showing detailed information" with no interaction with --json.
   • Fix: Document this special case explicitly in logs --help, or introduce a distinctly named flag (e.g., --json-verbose) to avoid overloading --verbose.

8. [Low] --dir/-d has different semantic meaning in doctor vs elsewhere

   • add, compile, lint, list, remove, update, upgrade, validate, fix, deploy: -d, --dir = workflow source directory.
   • doctor: -d, --dir = "Checkout directory to inspect" — a different concept, same flag name.
   • Fix: Rename doctor's flag to something like --checkout-dir to avoid semantic collision.

9. [Low] --format exists only in audit/logs, not elsewhere

   • audit, logs support --format (pretty/markdown/tsv/console) in addition to -j, --json; other commands with structured output (checks, compile, doctor, domains, experiments, forecast, health, list, outcomes, run, status, trial, upgrade, validate) only expose -j, --json.
   • Fix: If richer output formats are broadly useful, consider standardizing --format (with json as one enum value) across commands instead of maintaining a separate boolean --json.

10. [Low] Inconsistent phrasing of --no-X flag descriptions

    • "Skip X" (--no-gitattributes, --no-security-scanner, --no-check-update), "Remove X" (--no-stop-after: "Remove any stop-after field from the workflow"), "Override X" (--no-merge: "Override local changes with upstream version instead of merging"), "Refuse X" (--no-redirect: "Refuse updates when redirect frontmatter is present").
    • Fix: Standardize description phrasing to "Skip (behavior)" for all --no-X flags, matching the dominant existing pattern.

11. [Low] --no-firewall is a list filter, not a behavior-disabling switch

    • Description: "Filter to only runs without firewall enabled" — semantically different from all other --no-X flags which suppress an action rather than filter a list, blurring the meaning of the --no- prefix.
    • Fix: Rename to something like --without-firewall to distinguish list-filtering flags from behavior-disabling flags.

12. [Low] --dry-run is inconsistently available across mutating commands

    • Present in run, trial, env update.
    • Absent from other file/repo-mutating commands: deploy, update, upgrade, add, remove.
    • Fix: Add --dry-run uniformly to all state-changing commands, or explicitly document why it's intentionally absent for those commands.

13. [Low] --verbose uses "Enable X" phrasing while other boolean flags use imperative phrasing

    • --verbose: "Enable verbose output showing detailed information" (repeated ~48 times).
    • Other booleans use direct imperative wording instead, e.g. --auto-merge-prs: "Auto-merge any pull requests created during the workflow execution", --dry-run: "Preview workflow execution without triggering runs", --audit: "Check dependency health without performing upgrades".
    • Fix: Minor stylistic issue — adopt one convention (either "Enable/Disable X" or plain imperative) across all boolean flag descriptions.

14. [Low] --scope default/requiredness differs between env and secrets families

    • env get/env update: --scope defaults to repo (optional).
    • secrets bootstrap/secrets set: --scope is required (repo|org|ent), no default.
    • Same flag name, different requiredness rules across related command families.
    • Fix: Make --scope behavior consistent between env and secrets, or explicitly document the reasoning (e.g., secrets are more sensitive so require explicit scope) in both command's help text.

---

Notes / Non-Issues Confirmed Clean

• No typos found anywhere in the help output.
• No "Github" (incorrect casing) instances — all GitHub prose references and github.com/github/gh-aw path/URL references are correctly cased.
• Kebab-case flag naming is used consistently everywhere (no camelCase flags found).
• Shorthand flags -r, -d, -o, -f, -v, -j, -e (excluding the doctor/-l cases noted above) map consistently to the same meaning across all commands that use them.
• All sampled example command invocations in the docs use valid, matching flag names and syntax.
• All sampled default values (forecast --days, health --days, --cool-down, logs --count, etc.) match exactly between docs and CLI help.

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 · sonnet50 · 118.7 AIC · ⌖ 9.65 AIC · ⊞ 6.1K · ◷

• expires on Jul 30, 2026, 5:52 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

I 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 · gpt54 · 1.79 AIC · ⌖ 7.13 AIC · ⊞ 6.5K · ◷