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

Summary

Inspected the pre-collected help for about 55 top-level commands and subcommands (all-help.txt, 409 "Global Flags" blocks) and compared it with docs/src/content/docs/setup/cli.md.

Severity: high 0, medium 2, low 2.

Documentation gaps

1. work-queue subcommands missing from the docs (medium)

Affected: gh aw work-queue clear and gh aw work-queue dispatch <dispatcher>.
CLI output: gh aw work-queue clear [flags] and gh aw work-queue dispatch <dispatcher> both appear as Usage: lines.
Docs (cli.md, #### work-queue): "Subcommands: cancel-claim, cancel-work, compact, control, deploy, dispatch-next, evidence, explain, inspect, policy, reconcile, replay, reprioritize, state, stats, submit-work, submit-graph, trace, tui."
Expected: the docs list every subcommand the CLI exposes. Actual: clear and dispatch are absent.
Fix: add both to the list. Document clear --hard, --dry-run and --reason.
Priority: medium.

2. Flags with no mention anywhere under docs/, all in work-queue (medium)

--cancel-reserved (reconcile): "Cancel only if CAS proves no launch start marker exists (not a force release)"
--fairness-key, --graph-id, --node-key (submit-work)
--generation (control)
--max-bytes (dispatch-next): "Assignment byte budget, bounded by policy and host (default 49152)"
Fix: document these in the work-queue section of cli.md.
Priority: medium.

Flag and help inconsistencies

3. --repo description varies across commands (low)

Four variants appear in the help output:

136 commands: -r, --repo string Target repository ([HOST/]owner/repo format). Defaults to current repository
27 commands, including every work-queue subcommand: Target repository (owner/repo format)
9 commands: Target repository ([HOST/]owner/repo format). Required unless --org is provided
6 commands: Target repository (owner/repo format only; GHES host prefixes are not supported), with 2 of those adding Defaults to current repository
Expected: consistent wording that says whether a host prefix and the current-repo default are supported.
Fix: share one helper or constant for the flag description, and state the GHES limitation consistently.
Priority: low.

4. gh aw lint --json is the only --json flag with different semantics (low)

CLI output: --json Emit structured diagnostics (requires --rules)
Everywhere else (214 uses): -j, --json Output results in JSON format
lint and its 8 repeated help entries lack the -j short flag and the standard wording, and the flag only works with --rules.
Fix: add the -j short form, use standard wording, or document the exception.
Priority: low.

Inspection metadata

Date: 2026-10-19
Run: 39259999944
Method: manual scan of /tmp/gh-aw/agent/all-help.txt and help-output/. I compared flag names, short/long pairings and --no-* negations. I also checked that every flag in the help output is mentioned somewhere under docs/.
Checked and found consistent: every top-level command is referenced in cli.md, and the --no-* negation patterns are consistent.
Not done: I did not try the help examples, and I did not run spell-check or grammar tooling. A basic grep for common misspellings found nothing.

Generated by ✅ CLI Consistency Checker · copilot · auto · 26.2 AIC · ⌖ 0.614 AIC · ⊞ 8.5K · ◷

expires on Oct 21, 2026, 5:35 AM UTC-08:00

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