[cli-consistency] CLI Consistency Issues - 2026-06-02

[github-actions]

Summary

Comprehensive CLI consistency inspection of gh-aw (26 commands inspected, 2026-06-02). Issues grouped by category and severity.

Severity breakdown: 1 high · 7 medium · 6 low

---

High

H1 — e.g. missing trailing comma (5+ occurrences)

The standard typographic convention is e.g., (comma after). Several flag descriptions use e.g. without the comma, inconsistently with the majority of the codebase which uses e.g.,.

Affected lines (flag descriptions):

Command	Text
deploy, update	--cool-down ... (e.g. 7d, 24h, 0 to disable)
env (parent)	uses default_-prefixed lowercase keys (e.g. default_max_turns)
compile	--schedule-seed ... (e.g. "github/gh-aw")
domains	ecosystem identifiers (e.g. "node", "python", "github")
checks	third-party commit statuses (e.g. Vercel,

Expected: e.g., in all cases.

---

Medium

M1–M7 — Medium severity findings

M1 — --dry-run description inconsistency between run and trial

• run: --dry-run Validate workflow without actually triggering execution on GitHub Actions
• trial: --dry-run Show what would be done without making any changes

The word "Validate" in run is misleading — --dry-run does not perform validation; it simulates without executing. The trial version ("Show what would be done") is clearer and more accurate. These should use a consistent description style.

Suggested fix for run: Simulate execution without actually triggering the workflow on GitHub Actions

---

M2 — --pre-releases flag has three spellings in the same command's help text

In upgrade help:

• Example comment: # Include prerelease versions (one word, no hyphen)
• Flag description: Include pre-release versions ... ; prereleases are installed by exact tag

Three forms appear: prerelease, pre-release, and prereleases. Should be consistent throughout.

Suggested fix: Use pre-release (hyphenated) as the adjective and pre-releases as the noun throughout the description.

---

M3 — mcp list-tools description mismatch (parent vs Available Commands table)

In the mcp parent help, the Available subcommands bullet list says:

list-tools - List tools for a specific MCP server, or find workflows using it

But the Available Commands table in the same help output says:

list-tools List available tools for a specific MCP server

The two descriptions differ. The bullet list has the more complete description.

Suggested fix: Make both descriptions identical (prefer the longer one).

---

M4 — --disable-security-scanner uses lowercase markdown while other flags use Markdown

Flag description (on add, update, deploy, trial):

Disable security scanning of workflow markdown content

Elsewhere, Markdown is consistently capitalized (e.g., "Compile agentic workflow Markdown files", "all Markdown files in .github/workflows"). "markdown" in this flag description should be "Markdown".

Suggested fix: Disable security scanning of workflow Markdown content

---

M5 — --json example comments inconsistent across commands

The inline comment after --json examples varies:

• # Output in JSON format (checks, health, list, status)
• # Output results in JSON format (compile, validate, run, trial, audit, etc.)
• # Machine-readable JSON output (forecast)
• # Output audit results in JSON format (upgrade)
• # Output summary in JSON format (domains)
• # Output trial results in JSON format (trial)

All example comments for --json should use the same phrasing.

Suggested fix: Standardize to # Output in JSON format (short) or # Output results in JSON format (descriptive).

---

M6 — Docs vs CLI: outcomes --outcomes-dir flag missing from help examples

The CLI help for outcomes includes the --outcomes-dir flag, and the docs (cli.md) shows it in the Options list. However, the outcomes help examples section only shows three examples and never demonstrates --outcomes-dir in a concrete example:

gh aw outcomes 1234567890                # Check outcomes for a specific run
gh aw outcomes 1234567890 --json         # JSON output
gh aw outcomes 1234567890 --repo o/r     # Specify repository
gh aw outcomes 1234567890 -v             # Verbose output

Suggested fix: Add gh aw outcomes 1234567890 --outcomes-dir ./otlp # Write JSONL for OTLP export as a fourth example to match what the docs show.

---

M7 — Docs vs CLI: env update — docs shows --dry-run with -y/--yes, but env get has no short-form flags listed

The CLI help for env get shows --scope, --repo, --org, --enterprise without short forms. The env update has -y, --yes (a short form). This asymmetry is fine, but the env get short description in the parent env help is Download defaults into a YAML file with no period, while env update shows Upload defaults from a YAML file — neither has a period, which is consistent. ✓

However, the docs list --scope (required) for env update but the flag description in the CLI says only --scope string Variable scope (repo|org|ent) without marking it as required. This may confuse users.

Suggested fix: Add (required) or similar qualifier to the --scope flag description in env update help, or add a note that --scope defaults to repo when omitted.

---

Low

L1–L6 — Low severity findings

L1 — fix command numbered steps skip context

The fix command help describes steps 1–3 as "The command will:", then states "Without --write ... With --write, additionally:" before listing steps 4–7. Steps 4–7 start mid-list but their numbering continues without a re-introduction:

Without --write (dry-run mode), no files are modified. With --write, the command performs
all steps and additionally:
  4. Write updated files back to disk
  5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists
  ...

Step 4 is phrased as an infinitive ("Write updated files") while steps 1–3 use imperative verbs ("Scan", "Apply", "Report"). These should use consistent grammar.

Suggested fix: Change step 4 to Writes updated files back to disk (or change all to infinitives).

---

L2 — remove docs description doesn't match help

Docs say: "Remove workflows (both .md and .lock.yml). Accepts a workflow ID (basename without .md) or prefix pattern."

CLI help says: "Remove agentic workflow files matching the given filter." and separately: "You can provide a substring to match multiple workflows, or a specific workflow-id."

The docs say "prefix pattern" but the CLI says "substring". These are different matching strategies. If it really is substring (not prefix), the docs have a bug.

Verify which is correct and update docs or help accordingly.

---

L3 — trial --host-repo default format inconsistency

The --host-repo flag description uses angled brackets around the username: <username>/gh-aw-trial. This is the only flag description that uses <username> (all other --repo descriptions show owner/repo). Using <username> is fine but it breaks the pattern.

Suggested fix: (defaults to '<your-github-username>/gh-aw-trial'). Use '.' for current repository

---

L4 — upgrade --audit description in flag list differs from DEPENDENCY HEALTH AUDIT section

The --audit flag description: Check dependency health without performing upgrades

But the header section reads: DEPENDENCY HEALTH AUDIT: Use --audit to check dependency health without performing upgrades.

These are consistent, but the section header uses SCREAMING_SNAKE_CASE for "DEPENDENCY HEALTH AUDIT" which is visually inconsistent with all other section headers in help text. This appears to be the only help section using all-caps.

---

L5 — secrets parent help uses bullet-list style for subcommands, inconsistent with mcp and pr

secrets:

Available subcommands:
  - set       - Create or update individual secrets
  - bootstrap - Validate and configure all required secrets for workflows

mcp:

Available subcommands:
  - list       - List MCP servers defined in agentic workflows
  - list-tools - List tools for a specific MCP server, or find workflows using it
  ...

These use the same style (consistent ✓), but project uses a slightly different style with no colon in the leading bullet:

Available subcommands:
  - new - Create a new GitHub Project V2 board

Minor formatting inconsistency. All are readable but should be standardized.

---

L6 — logs flag --no-staged description vs --firewall/--no-firewall style inconsistency

• --firewall: Filter to only runs with firewall enabled
• --no-firewall: Filter to only runs without firewall enabled
• --no-staged: Exclude workflow runs that executed in staged mode (safe outputs previewed but not applied)

The --no-staged uses "Exclude" while --no-firewall uses "Filter to only runs without". For consistency, --no-staged could follow the same pattern: Filter to only runs that did not execute in staged mode (safe outputs previewed but not applied).

---

Inspection Metadata

• 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, forecast, health, list, logs, status, completion, hash-frontmatter, mcp-server, pr, project, outcomes, version)
• Date: 2026-06-02
• Method: Direct CLI invocation (./gh-aw [cmd] --help) + comparison with docs/src/content/docs/setup/cli.md
• Binary: Pre-built binary at /home/runner/work/gh-aw/gh-aw/gh-aw

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 890.7K · ◷

• expires on Jun 4, 2026, 2:46 PM UTC

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

Priority: Documentation/CLI consistency (45 points)

If assignment succeeds, the Copilot coding agent will fix the CLI flag descriptions and create a pull request.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · haiku45 29.1K · ◷