[cli-consistency] CLI Consistency Issues - 2026-10-21 #70893

Summary

Inspected the gh aw help output (main help plus ~46 commands) and compared it with docs/src/content/docs/setup/cli.md. Command and flag coverage in the docs is otherwise complete. Documentation drift: none found. I found no typos or broken examples in the pre-collected output. The findings are all flag-naming inconsistencies:

• High: 0
• Medium: 1
• Low: 2

Flag inconsistencies

1. --timeout uses three different units and types (medium)

Affected commands: trial, logs, forecast, audit, and the other command that shows Wall-clock retrieval deadline (default 5m0s).

trial:    --timeout int      Execution timeout in minutes (0 = no timeout) (default 30)
logs:     --timeout int      Total download timeout in minutes across all targets (0 = no timeout)
forecast: --timeout int      Gracefully stop forecast computation after this many minutes (0 = no timeout)
audit:    --timeout duration Maximum audit duration (e.g., 50s or 5m; 0 means no additional deadline).
(other):  --timeout duration Wall-clock retrieval deadline (default 5m0s)

• Expected: one convention, for example a duration type everywhere.
• Actual: some commands take integer minutes and others take Go durations.
• Suggested fix: migrate to duration, keeping integer-minute values as a deprecated alias. At minimum, make the units explicit in the docs.

2. lint --json has no -j short flag (low)

lint:       --json    Emit structured diagnostics (requires --rules)
compile:  -j, --json  Output results in JSON format

All other commands that offer --json also offer -j, with the same description.

• Suggested fix: add -j to lint, or document why it is deliberately omitted.
• Note: the semantics differ because lint --json requires --rules.

3. --dry-run has different meanings across commands (low)

compile: --dry-run  Compile with strict validation, shellcheck, and model checks; reject existing and ...
run:     --dry-run  Preview workflow execution without triggering runs on GitHub Actions
trial:   --dry-run  Preview trial execution without creating repos or running workflows
logs:    --dry-run  Filter to only dry-run workflow runs

On logs, the flag is a filter rather than a preview. On compile, it is a stricter compile mode.

• Suggested fix: rename the logs flag (for example to --only-dry-run) or make the descriptions unmistakable. Document the compile semantics clearly.

Inspection metadata

• Date: 2026-10-21
• Method: scripted comparison of /tmp/gh-aw/agent/all-help.txt and help-output/*.txt against the per-command sections of cli.md. This covered flags missing from the docs, short/long flag pairs, and description consistency.
• Run: 39607312328

Generated by ✅ CLI Consistency Checker · copilot · auto · 27.2 AIC · ⌖ 0.615 AIC · ⊞ 8.5K · ◷

• expires on Oct 23, 2026, 5:32 AM UTC-08:00