[cli-consistency] CLI Consistency Issues - 2026-08-31

[github-actions]

Summary

Performed a full inspection of gh aw CLI help output (/tmp/gh-aw/agent/all-help.txt, ~25k lines covering all commands/subcommands) against docs/src/content/docs/setup/cli.md. Cross-checked flag lists, terminology, examples, and descriptions across every top-level command (init, add, add-wizard, new, secrets, doctor, fix, compile, validate, lint, trial, run, list, status, logs, audit, graders, outcomes, models, health, checks, forecast, experiments, enable, disable, remove, update, deploy, upgrade, env, mcp, pr transfer, mcp-server, domains, version, completion, project, hash-frontmatter).

Severity breakdown: 0 high, 0 medium, 1 low.

The CLI is in good shape overall — flag naming, --no-... negation patterns, short/long flag pairings, and terminology are consistent across commands, and the vast majority of doc "Options:" lists match the actual flag sets exactly.

Finding (low severity) — already fixed

Category: Documentation gap (missing flag in Options summary)

Affected command: gh aw logs

Details: gh aw logs --help includes a --graders flag:

      --graders                Filter to runs containing deterministic grader results; automatically includes grader artifacts

but the corresponding **Options:** summary line for logs in docs/src/content/docs/setup/cli.md omitted --graders (all other logs flags were listed).

Expected vs actual:

• Expected: --graders listed alongside the other 28 flags in the logs Options summary.
• Actual: flag was missing from the doc list, even though it's demonstrated in the CLI's own --graders example (gh aw logs --graders # Filter logs from workflows with graders results).

Fix applied: Added --graders to the Options line in docs/src/content/docs/setup/cli.md (line 546).

Priority: low (cosmetic doc completeness only; flag still worked and was documented via --help).

Inspection metadata

• Commands inspected: all top-level and subcommands listed in gh aw --help, using pre-collected output in /tmp/gh-aw/agent/all-help.txt and per-command files in /tmp/gh-aw/agent/help-output/ (462 files).
• Method: systematic per-command review of Usage, Examples, Flags, and Global Flags blocks, cross-referenced against docs/src/content/docs/setup/cli.md section-by-section (Options lists, flag descriptions, examples, cross-links). Also ran a scripted flag-set diff (regex-extracted CLI flags vs. doc **Options:** lines) for the more flag-heavy commands (compile, validate, lint, run, logs, audit, trial, deploy, update, upgrade, forecast, add, add-wizard, init, doctor) to catch any other omissions.
• Date: 2026-08-31.
• No typos, grammar issues, inconsistent flag naming, or invalid examples were found elsewhere in the reviewed help text or documentation.

Generated by ✅ CLI Consistency Checker · copilot · auto · 139.8 AIC · ⌖ 9.44 AIC · ⊞ 7.1K · ◷

• expires on Sep 2, 2026, 5:37 AM UTC-08:00