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

[github-actions]

Summary

Automated CLI consistency inspection of gh aw ran on 2026-06-10. 9 issues found across CLI help text and documentation (docs/src/content/docs/setup/cli.md).

Severity	Count
medium	3
low	6

Total commands inspected: 30+ (all top-level commands and key subcommands)

---

Category: Docs Missing CLI Flags (medium)

2 flags present in CLI help but absent from docs options list

1. forecast --timeout — missing from docs options list

• Affected command: gh aw forecast
• Docs file: docs/src/content/docs/setup/cli.md line 592
• CLI output:

  --timeout int     Gracefully stop forecast computation after this many minutes (0 disables timeout)
  

  CLI examples include: gh aw forecast --timeout 10 # Stop gracefully after 10 minutes
• Docs options list (line 592): `--days`, `--period`, `--sample`, `--eval`, `--repo/-r`, `--json/-j`
• Expected: --timeout should be added to the options list
• Priority: medium

2. compile --gh-aw-ref — missing from docs options list

• Affected command: gh aw compile
• Docs file: docs/src/content/docs/setup/cli.md line 294
• CLI output:

  --gh-aw-ref string   Compile workflows to reference github/gh-aw at the given branch, tag, or SHA
                       (e.g. main, my-feature, abc123). Convenience alias for --action-mode release
                       --action-tag <ref>.
  

• Docs options list (line 294): does not include --gh-aw-ref
• Expected: --gh-aw-ref should be added to the compile options list
• Priority: medium

---

Category: Incorrect Inline Comment in Docs (medium)

3. gh aw mcp add (no-arg) — misleading inline comment

• Affected command: gh aw mcp add
• Docs file: docs/src/content/docs/setup/cli.md line 726
• Docs (current):

  gh aw mcp add                              # Add MCP tool to workflow

• CLI help (actual behavior):

  gh aw mcp add                                          # List available MCP servers

  CLI description: "When called with no arguments, it will show a list of available MCP servers from the registry."
• Expected: comment should read # List available MCP servers (not # Add MCP tool to workflow)
• Priority: medium

---

Category: Terminology Inconsistencies (low)

3 inconsistencies in how concepts are named across main help, detailed help, and docs

4. forecast description — "token usage" vs "AI Credit (AIC)"

• Affected command: gh aw forecast
• Docs intro (line 578): "Forecast token usage and costs for agentic workflows..."
• CLI detailed help first line: "[EXPERIMENTAL] Forecast AI Credit (AIC) usage for agentic workflows"
• Issue: Docs use "token usage" terminology while CLI uses "AI Credit (AIC)". These should be aligned.
• Priority: low

5. (experimental) vs [EXPERIMENTAL] formatting

• Affected command: gh aw forecast
• CLI main listing: forecast Forecast AI Credit usage and costs for agentic workflows (experimental)
• CLI detailed help: [EXPERIMENTAL] Forecast AI Credit (AIC) usage for agentic workflows
• Docs: #### `forecast` `[EXPERIMENTAL]`
• Issue: Main CLI listing uses lowercase (experimental) in parentheses; detailed help and docs consistently use uppercase [EXPERIMENTAL] in brackets.
• Priority: low

6. forecast short description — "and costs" mismatch

• Affected command: gh aw forecast
• CLI main listing: "Forecast AI Credit usage and costs for agentic workflows (experimental)"
• CLI detailed help first line: "[EXPERIMENTAL] Forecast AI Credit (AIC) usage for agentic workflows"
• Issue: Main listing says "usage and costs" but detailed help says just "usage" — the "and costs" phrase is dropped.
• Priority: low

---

Category: CLI Description Abbreviated vs Docs (low)

2 commands have shorter descriptions in CLI than in docs

7. env get short description — missing context

• Affected command: gh aw env get
• CLI help: "Download defaults into a YAML file"
• Docs: "Download default compiler variables into a YAML file"
• Issue: CLI omits "compiler" context, making it less clear what "defaults" refers to.
• Priority: low

8. env update short description — missing context

• Affected command: gh aw env update
• CLI help: "Upload defaults from a YAML file"
• Docs: "Upload default compiler variables from a YAML file"
• Issue: Same as above — CLI omits "compiler" context.
• Priority: low

---

Category: Documentation Style (low)

9. Inconsistent flag shorthand notation in docs options lists

• Affected commands: multiple
• Issue: Some commands document short flag forms consistently (`--dir/-d`, `--engine/-e`) while others omit the short form (e.g., update options list shows --engine and --dir without -e/-d). This is inconsistent across the docs.
• Examples:
  • init options: `--engine/-e` ✓
  • compile options: `--dir/-d`, `--engine/-e` ✓
  • update options: `--engine`, `--dir` (missing -e/-d)
• Priority: low

---

Inspection Metadata

• Commands inspected: 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 + key subcommands
• Date: 2026-06-10
• Method: Live CLI invocation (gh aw <cmd> --help) compared against docs/src/content/docs/setup/cli.md
• Workflow run: 27282376237

Generated by ✅ CLI Consistency Checker · ⌖ 13.6 AIC · ⊞ 15.8K · ◷

• expires on Jun 12, 2026, 6:23 AM UTC-08:00