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

[github-actions]

Summary

Comprehensive CLI consistency inspection performed on 2026-07-14 against /tmp/gh-aw/agent/all-help.txt (pre-collected help output for all 26 gh aw commands).

Severity Breakdown

Severity	Count
🔴 High	4
🟡 Medium	12
🟢 Low	10
Total	26

---

🔴 High — Flag Gaps Blocking Functionality

F1 — --engine missing from gh aw upgrade

upgrade runs compilation internally but silently ignores the AI engine. Every other compilation-touching command has -e, --engine.

Affected: gh aw upgrade
Expected: -e, --engine string — Override AI engine (copilot, claude, codex, gemini, crush)
Suggested fix: Add -e, --engine to gh aw upgrade.

---

F2 — --approve missing from gh aw update

update recompiles workflows (unless --no-compile is set). compile, run, and upgrade all have --approve to bypass strict-mode manifest enforcement. update has no way to pass this flag.

Affected: gh aw update
Expected: --approve (same description as in compile/run/upgrade)
Suggested fix: Add --approve to gh aw update.

---

F3 — --no-security-scanner missing from compile and validate

compile and validate process workflow Markdown but have no way to skip the built-in security scanner, even though every installation command (add, add-wizard, deploy, update, trial) exposes --no-security-scanner.

Affected: gh aw compile, gh aw validate
Suggested fix: If these commands run the built-in security scanner, add --no-security-scanner to both.

---

F4 — -r, --repo missing from gh aw upgrade

upgrade supports --org and --repos (glob) but has no single-repository -r, --repo flag. Its sibling update has all three. There is no way to upgrade a single non-current remote repository.

Affected: gh aw upgrade
Expected: -r, --repo string — same description as in update (Target repository ([HOST/]owner/repo format). Defaults to current repository)
Suggested fix: Add -r, --repo to gh aw upgrade.

---

🟡 Medium — Flag Inconsistencies & Docs Gaps

Flag inconsistencies (click to expand)

F5 — --disable-codemod breaks universal --no-* negation pattern

Every skip/disable flag in the CLI uses --no-* (--no-fix, --no-compile, --no-merge, etc.). fix and upgrade alone use --disable-codemod.

Affected: gh aw fix, gh aw upgrade
Quoted text: --disable-codemod strings Disable specific codemod IDs during the fix step (repeatable)
Suggested fix: Rename to --no-codemod strings (or --skip-codemod strings) to match --no-* convention.

---

F6 — --create-pull-request missing from gh aw deploy

deploy writes workflow files to repositories non-interactively. add, init, update, and upgrade all have --create-pull-request; deploy does not.

Affected: gh aw deploy
Suggested fix: Add --create-pull-request to gh aw deploy.

---

F7 — -j, --json absent from add, deploy, remove, update

All analysis/observation commands have --json. Among mutation commands, upgrade/compile/run/trial have it. add, add-wizard, deploy, remove, update do not, making machine-readable CI scripting inconsistent.

Affected: gh aw add, gh aw deploy, gh aw remove, gh aw update
Suggested fix: Add -j, --json to these commands.

---

F8 — --no-gitattributes missing from gh aw update

add, add-wizard, and deploy all have --no-gitattributes. update reinstalls workflows (same code path) but lacks this flag.

Affected: gh aw update
Suggested fix: Confirm whether update modifies .gitattributes; if so, add --no-gitattributes.

---

F9 — -f, --force has 3 distinct meanings

-f/--force is reused with unrelated semantics across commands:

1. add, deploy, new: "Overwrite existing workflow files without confirmation"
2. compile: "Force overwrite of existing dependency files (e.g., dependabot.yml)"
3. update: "Force update even if no changes are detected"

Additionally: gh aw new is missing the word "workflow" in its --force description — "Overwrite existing files without confirmation" vs "Overwrite existing workflow files without confirmation" elsewhere.

Affected: gh aw new (description), gh aw compile (consider rename), gh aw update (consider rename)
Suggested fix: Standardize new's description to include "workflow". Consider renaming update's -f to --force-update and documenting compile's more explicitly.

---

F10 — --enable-if-needed present in run but missing from trial

Both run and trial trigger workflow executions. trial likely also needs to enable a workflow if it isn't already active.

Affected: gh aw trial
Quoted CLI text (run): --enable-if-needed Enable the workflow before running if needed, and restore state afterward
Suggested fix: Add --enable-if-needed to gh aw trial (or document in help why it's not needed).

---

F11 — -o, --output missing default value in gh aw outcomes

audit and logs both document (default ".github/aw/logs") in their --output description. outcomes omits this.

Affected: gh aw outcomes
Quoted text (audit/logs): Output directory for generated files (default ".github/aw/logs")
Quoted text (outcomes): Output directory for generated files
Suggested fix: Add (default ".github/aw/logs") to outcomes's --output description, or note if there is no default.

Docs vs CLI mismatches (click to expand)

D1 — gh aw audit: --evals flag not documented

--evals exists in the CLI but is absent from cli.md's options list.

CLI text: --evals Skip runs that do not contain evals results (evals.jsonl); automatically downloads the evals artifact when --artifacts is narrowed
Impact: medium

---

D2 — gh aw audit: evals missing from --artifacts valid values in docs

Docs say (valid sets): activation, agent, all, detection, experiment, firewall, github-api, mcp, and usage
CLI says: activation, agent, all, detection, **evals**, experiment, firewall, github-api, mcp, usage
Impact: medium

---

D3 — gh aw logs: multiple undocumented flags

The following flags appear in the CLI but are absent from cli.md:

• --evals — Filter to runs containing evals results
• --exclude-staged — Exclude workflow runs that executed in staged mode
• --report-file string — Write markdown output directly to a file path
• --filtered-integrity — Filter to runs containing items filtered by gateway integrity checks
• --after-run-id int / --before-run-id int — ID range filtering

Impact: medium (useful functionality undiscoverable from docs)

---

D4 — gh aw logs: --format valid values not enumerated in docs

CLI says: console (decorated tables), tsv (tab-separated), pretty (cross-run report), markdown (cross-run Markdown). Default: compact agent-optimized output
Docs: List the flag but do not enumerate valid values.
Impact: medium

---

D5 — gh aw run: --ref example comment is misleading

Docs (line 390): gh aw run workflow --push --ref main # Push to specific branch
CLI: --ref string Branch or tag name to **run the workflow on** (default: current branch) — controls dispatch target, not push destination.
Impact: medium — users may think --ref redirects the push.

---

D6 — gh aw status: --ref description mismatch

Docs: "With --ref, includes latest run status"
CLI: --ref string Filter runs by branch or tag name (e.g., main, v1.0.0)
Impact: medium — "includes latest run status" vs. "filters runs" are different behaviors.

---

D7 — gh aw mcp-server: --cmd description mismatch

Docs: --cmd (custom subprocess command)
CLI: --cmd string Path to gh aw command to use (defaults to 'gh aw') — specifically a path to the gh aw binary.
Impact: low

---

🟢 Low — Wording & Style Issues

Wording and style issues (click to expand)

W1 — "markdown" should be capitalized "Markdown" in multiple places

"Markdown" is a proper noun. Several flag descriptions use lowercase "markdown":

• gh aw add, add-wizard, deploy, update, trial: "Skip security scanning of workflow markdown content" → "workflow Markdown content"
• gh aw add, add-wizard: "text/markdown → treated as a gh-aw workflow markdown file" → "workflow Markdown file"
• gh aw hash-frontmatter: "Template expressions containing env. or vars. from the markdown body" → "the Markdown body"

---

W2 — "in name" → "in the name" (missing article)

Multiple example comments are missing the article "the":

• gh aw remove: "# Remove all workflows containing 'test-' in name" → "in the name"
• gh aw list: "# List workflows with 'ci-' in name" → "in the name"
• gh aw status: "# Show workflows with 'ci-' in name" → "in the name"

---

W3 — "cooldown" vs "cool-down" inconsistency

The flag --cool-down uses a hyphen, but example comments use the unhyphenated form:

• gh aw update, gh aw deploy: "# Disable cooldown and apply all pending releases immediately" → "cool-down"
• "# Apply a custom 3-day cooldown period" → "cool-down period"

---

W4 — gh aw status example: "Show all workflow status" — grammatical issue

"# Show all workflow status" is grammatically awkward (missing plural or article).
Suggested fix: "# Show status of all workflows" (matching the command's own description)

---

W5 — gh aw upgrade: missing period at end of flag behavior sentence

Quoted text: "Upgrade runs codemods, action version updates, and workflow compilation by default; use --no-fix to skip all three steps"
Suggested fix: Add a period at the end: "...skip all three steps."

---

W6 — -F (uppercase) is the only uppercase short flag in the CLI

gh aw run has -F, --raw-field stringArray. All other short flags are lowercase. This is likely intentional to mirror gh CLI's convention, but is inconsistent within gh aw.

Suggested fix: Either document this intentionally or align with lowercase-only short flags.

---

Inspection Metadata

Item	Value
Commands inspected	26 (add, add-wizard, deploy, env, init, new, remove, secrets, update, upgrade, compile, domains, fix, lint, mcp, validate, disable, enable, run, trial, audit, checks, experiments, forecast, health, list, logs, outcomes, status, completion, hash-frontmatter, mcp-server, pr, project)
Inspection date	2026-07-14
Method	Pre-collected help output + docs comparison + flag cross-analysis
Run	29337493575

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 · 189.8 AIC · ⌖ 10.7 AIC · ⊞ 4.4K · ◷

• expires on Jul 16, 2026, 5:54 AM UTC-08:00