[cli-consistency] CLI Consistency Issues - 2026-11-05 #75181

Summary

Inspected the pre-collected help for about 45 top-level commands, plus subcommand and flag help files, against docs/src/content/docs/setup/cli.md.

Severity: high 0, medium 0, low 2. No typos were found by keyword scan. Every top-level command is documented. All --dir defaults use .github/workflows consistently.

Findings

1. gh aw lint --json has no -j short flag (low)

• Every other command with --json pairs it with -j: audit, checks, compile, doctor, domains, forecast, health, list, logs, models, run, status, trial, upgrade and validate.

• lint help shows the flag with no short form:

    --json                                  Emit structured diagnostics (requires --rules)
  

• Expected: -j, --json, or an explicit note that the omission is intentional.

• The docs **Options:** line for lint also lists plain --json.

• Suggested fix: add the -j shorthand to lint and update the docs.

2. Docs logs Options line omits --episodes, --outcomes and --outcomes-dir (low)

• Help for gh aw logs includes these flags. The quoted lines below are from help-output/logs.txt:

  Use --outcomes to evaluate the current GitHub state of each selected run's safe
  ...
      --episodes                        Include recorded episode membership and hops; combine with --outcomes for episode outcome summaries
  

• The main **Options:** list for logs in cli.md (about line 754) does not mention them.

• They are only documented in the separate logs --outcomes section (about line 1047), and that section's options line omits --outcomes itself.

• Suggested fix: add the three flags to the main logs Options list.

Inspection metadata

• Date: 2026-11-05

• Run: 42033865672

• Method:

  • Read /tmp/gh-aw/agent/all-help.txt and help-output/*.txt.
  • Cross-checked the **Options:** lines in cli.md against help flags, using a script.
  • Compared short and long flag pairings across commands.
  • Scanned for typos.

• Not reported: --pr is a documented compatibility alias for --create-pull-request. It appears in cli.md but not as a flag line in help, and it is mentioned in the help text of add, deploy and others.

Generated by ✅ CLI Consistency Checker · copilot · auto · ~33 AIC · ⌖ ~1 AIC · ⊞ 4.4K · ◷

• expires on Nov 7, 2026, 5:31 AM UTC-08:00