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

[github-actions]

Summary

Comprehensive CLI consistency inspection performed on gh aw CLI help output and docs/src/content/docs/setup/cli.md.

Severity breakdown:

• 🔴 High: 0
• 🟡 Medium: 3
• 🟢 Low: 16

Total findings: 19

---

Findings

Grammar

Grammar issues (2 findings)

1.1 Broken grammar in docs "When to use" column — add-wizard row

• Severity: Medium
• File: docs/src/content/docs/setup/cli.md, line 16
• Current:

  | [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup | Adding a community workflow and want guided prompts for secrets and auth |
  

• Issue: "Adding a community workflow and want guided prompts..." — the gerund phrase (Adding...) has no matching continuation; want is a finite verb that creates an incomplete clause.
• Suggested fix: When adding a community workflow and wanting guided prompts for secrets and auth

---

1.2 Mixed tense in gh aw fix numbered steps

• Severity: Low
• Location: gh aw fix --help, steps list
• Current:

  The command will:
    1. Scan workflow files for deprecated fields.
    2. Apply relevant codemods to fix issues.
    3. Report what was changed in each file.
  ...additionally:
    4. Writes updated files back to disk.
    5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists.
  

• Issue: Steps 1–3, 5–8 use imperative form (Scan, Apply, Delete). Step 4 uses third-person present tense (Writes).
• Suggested fix: Change step 4 to Write updated files back to disk. Also: With --write, the command first performs steps 1–3 and then additionally: (the current phrasing "performs all steps and additionally" is ambiguous).

---

Capitalization

Capitalization inconsistencies (2 findings)

2.1 markdown not capitalized in docs table

• Severity: Low
• File: docs/src/content/docs/setup/cli.md, line 19
• Current: Convert markdown to GitHub Actions YAML
• Help text: Compile agentic workflow Markdown files into GitHub Actions YAML.
• Suggested fix: Change markdown → Markdown in the docs table cell.

---

2.2 markdown not capitalized in --no-security-scanner flag descriptions

• Severity: Low
• Affected commands: add, add-wizard, deploy, update, trial (5+ commands)
• Current: Skip security scanning of workflow markdown content
• Suggested fix: Skip security scanning of workflow Markdown content

---

Flag Inconsistencies

Flag inconsistencies (4 findings)

3.1 --approve flag: trailing period in run, absent in compile/update/upgrade

• Severity: Low
• gh aw run: --approve Approve safe update manifest changes when --push triggers an automatic recompile step. ...pass this flag to approve those changes. (ends with period)
• gh aw compile/update/upgrade: --approve Approve all safe update changes. ...Use this flag to approve and skip safe update enforcement (no trailing period)
• Suggested fix: Remove trailing periods from run version; standardize wording across all four commands.

---

3.2 --push flag ends with period; neighboring flags do not

• Severity: Low
• gh aw run --push: Commit and push workflow files (including transitive imports) before running. Refuses to proceed when unrelated files are already staged. (ends with period)
• Suggested fix: Remove trailing period, consistent with the majority of flag descriptions in the CLI.

---

3.3 gh aw doctor --repo missing [HOST/] format qualifier ⚠️

• Severity: Medium
• gh aw doctor: --repo string Target repository (owner/repo format)
• Every other command: --repo string Target repository ([HOST/]owner/repo format). ...
• Issue: doctor is documented as supporting GHES in its prose, but the flag description omits the [HOST/] prefix, suggesting it may not handle GHES host-prefixed slugs.
• Suggested fix: Target repository ([HOST/]owner/repo format) — consistent with all other commands.

---

3.4 gh aw secrets help shows two different descriptions for bootstrap subcommand

• Severity: Low
• "Available subcommands" section: bootstrap - Analyze workflows and set up required secrets
• "Available Commands" section (same screen): bootstrap Analyze workflows and interactively configure required secrets
• Suggested fix: Unify to: Analyze workflows and interactively configure required secrets

---

Docs vs Help Mismatches

Docs-vs-help mismatches (10 findings)

4.1 secrets command description mismatch

• Severity: Low
• Docs: Manage GitHub Actions secrets and tokens.
• Help: Manage GitHub Actions secrets for agentic workflows.
• Suggested fix: Align docs to: Manage GitHub Actions secrets for agentic workflows.

---

4.2 health command description omits "and execution trends"

• Severity: Low
• Docs: Display workflow health metrics and success rates.
• Help: Display workflow health metrics, success rates, and execution trends.
• Suggested fix: Align docs to match help text.

---

4.3 env command description uses different phrasing

• Severity: Low
• Docs: Manage compiler defaults as GitHub variables at repository, organization, or enterprise scope.
• Help: Manage compiler default variables in bulk for a repository, organization, or enterprise scope.
• Suggested fix: Align docs to: Manage compiler default variables in bulk for a repository, organization, or enterprise scope.

---

4.4 new command: completely different descriptions

• Severity: Low
• Docs: Create a workflow template in .github/workflows/, or launch the interactive wizard when no workflow name is provided.
• Help: Create a new agentic workflow file with example configuration and explanations of all available options.
• Suggested fix: Docs should reflect the help text as authoritative source, or a merged description covering both aspects.

---

4.5 remove help text is vague compared to docs

• Severity: Low
• Docs: Specifies removal of both .md and .lock.yml files with substring matching support.
• Help: Remove agentic workflow files matching the given filter. (no mention of dual-file removal)
• Suggested fix: Help text → Remove agentic workflow files (.md and .lock.yml) matching the given filter.

---

4.6 validate --fail-fast example comment mismatch

• Severity: Low
• Docs: gh aw validate --fail-fast # Stop at the first error
• Help: gh aw validate --fail-fast # Stop at the first validation error
• Suggested fix: Docs → # Stop at the first validation error

---

4.7 compile first example comment mismatch

• Severity: Low
• Docs: gh aw compile # Compile all workflows
• Help: gh aw compile # Compile all Markdown files
• Suggested fix: Docs → # Compile all Markdown files

---

4.8 run description: docs adds unconfirmed claim, phrasing differs

• Severity: Low
• Docs: Execute workflows immediately in GitHub Actions. Displays workflow URL for tracking.
• Help: Run one or more agentic workflows on GitHub Actions using the workflow_dispatch trigger.
• Issue: "Displays workflow URL for tracking" appears only in docs; help doesn't confirm this behavior. Phrasing is substantially different.
• Suggested fix: Align to help text wording; add URL tracking note to help if accurate.

---

4.9 disable docs omits "or all workflows if no IDs provided"

• Severity: Low
• Docs: Disable one or more workflows and cancel any in-progress runs.
• Help: Disable one or more workflows by ID, or all workflows if no IDs are provided. Any in-progress runs will be canceled before disabling.
• Suggested fix: Disable one or more workflows (or all if no IDs provided) and cancel any in-progress runs.

---

4.10 deploy description: different vocabulary and missing "purge enabled"

• Severity: Low
• Docs: "Roll out", "refreshes existing sourced workflows", "recompiles lock files with purge enabled"
• Help: "Deploy", "updating existing workflows", "compiling lock files" (no mention of purge)
• Suggested fix: Add "with purge enabled" to help text lock file step; standardize "Roll out"/"Deploy" vocabulary.

---

Style Inconsistencies

6.1 trial options use reversed flag order in docs

• Severity: Low
• trial options in docs: -e/--engine (short flag first)
• All other commands in docs: --engine/-e (long flag first)
• Suggested fix: Change to --engine/-e to match standard order throughout the document.

---

8.2 Unique (Cache eviction) parenthetical prefix in --cache-before flag

• Severity: Low
• Location: gh aw logs --help
• Current: --cache-before string (Cache eviction) Evict locally cached run folders ...
• Issue: This parenthetical tag pattern is used only on this one flag; no other flag uses it.
• Suggested fix: Remove the parenthetical prefix: Evict locally cached run folders before this date (cache cleanup). Accepts deltas like -1d, -1w, ...

---

Inspection Metadata

Field	Value
Date	2026-07-24
Commands inspected	25 (add, add-wizard, deploy, doctor, 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, version)
Docs file	docs/src/content/docs/setup/cli.md
Help source	Live ./gh-aw [command] --help output
Method	CLI output vs documentation cross-reference

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 · sonnet46 · 168.2 AIC · ⌖ 10.1 AIC · ⊞ 4.6K · ◷

• expires on Jul 26, 2026, 5:53 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

I have 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 · 3.28 AIC · ⌖ 9.47 AIC · ⊞ 7.5K · ◷