[cli-consistency] CLI Consistency Issues - 2026-10-08 #66893

Summary

Inspected ~45 top-level commands (plus subcommands, 510 help files) from /tmp/gh-aw/agent/all-help.txt. Found 2 issues: 0 high, 1 medium, 1 low.

Documentation gaps

1. work-queue is not documented in docs/src/content/docs/setup/cli.md (medium)

• Affected: gh aw work-queue and subcommands cancel-claim, cancel-work, claim, compact, finish, replay, stats, submit-work.
• CLI output: work-queue Experimental: inspect and update a Git-backed work queue (listed under "Utilities").
• Actual: every other top-level command has a gh aw <cmd> entry in cli.md; work-queue has none (neither its flags --branch, --claim-id, --work-id, --attempt-id, --run-id, --file).
• Suggested fix: add a section (marked experimental) under "Utility Commands" covering the subcommands and flags.

Flag-naming inconsistencies

2. work-queue uses non-standard --repo / --json flags (low)

• Quoted output:

  --json            Output JSON
  --repo string     GitHub repository owner/repo
  

• Elsewhere (164 and 116 occurrences respectively): -j, --json Output results in JSON format and -r, --repo string Target repository ([HOST/]owner/repo format). Defaults to current repository.
• Expected: short flags -j/-r and the standard description wording (or a documented reason for omitting GHES host support).
• Suggested fix: align work-queue flag definitions with the shared helpers used by other commands.

Inspection metadata

• Date: 2026-10-08; method: scripted comparison of all flags in per-command help files against cli.md, plus review of flag/description patterns (--engine, --repo, --json, --output).

Generated by ✅ CLI Consistency Checker · copilot · auto · 20 AIC · ⌖ 0.593 AIC · ⊞ 8.4K · ◷

• expires on Oct 10, 2026, 5:34 AM UTC-08:00