Summary
Automated CLI consistency inspection (2026-06-19) against the gh-aw binary and docs/src/content/docs/setup/cli.md. 34 commands inspected, 20 issues found.
| Severity |
Count |
| ๐ด High |
1 |
| ๐ก Medium |
7 |
| ๐ข Low |
12 |
๐ด High
H1 โ --dry-run semantics differ between run and trial
run --dry-run: "Validate workflow without actually triggering execution on GitHub Actions"
trial --dry-run: "Show what would be done without making any changes"
trial --dry-run is broader (no changes at all) while run --dry-run only skips dispatch. Users expect consistent semantics. Fix: align descriptions or rename trial's variant to --plan/--preview.
๐ก Medium
M1 โ Missing article in --append flag (3 commands: add, deploy, trial)
Text: "Append extra content to the end of agentic workflow on installation" โ missing "the" before "agentic workflow".
M2 โ Missing article in trial help body
"All workflows must support workflow_dispatch trigger to be used in trial mode." โ missing "the" before "workflow_dispatch trigger".
M3 โ --stdin descriptions differ between audit and logs
audit: "...instead of positional arguments"
logs: "...instead of discovering runs via the GitHub API"
Same flag, different explanations. Fix: unify wording.
M4 โ --dir description inconsistent: lint vs all others
- Others:
"Workflow directory (default: .github/workflows)"
lint: "Directory to scan for *.lock.yml files when no arguments are provided (default \".github/workflows\")"
Fix: normalize phrasing and default-value style.
M5 โ --logical-repo short flag -l only on trial, not compile
Both commands have --logical-repo but only trial exposes -l. Descriptions also diverge. Fix: add -l to compile or remove it from trial; unify descriptions.
M6 โ --force covers three different behaviors
add/deploy/new: overwrite files
update: force update even without changes
compile: overwrite dependency files only
Fix: rename specialized variants (--force-update, --force-deps) or add inline disambiguation.
M7 โ --verbose docs vs CLI mismatch
- Docs:
"Enable verbose output with debugging details"
- CLI:
"Enable verbose output showing detailed information"
Fix: align both to the same wording.
๐ข Low (12 issues)
L1 โ "VSCode" โ "VS Code" in init help
"Configures VSCode settings (.vscode/settings.json)" โ incorrect brand capitalization.
L2 โ Missing "the" before "expires field" in init help
"if any workflows use expires field for discussions or issues" โ "the expires field"
L3 โ Awkward phrasing in init Codespaces bullet
"- Adds GitHub Copilot extensions and gh aw CLI installation" โ "...and installs the gh aw CLI"
L4 โ Missing "the" before "GitHub API" in compile help
"resolving all action SHAs from GitHub API" โ "from the GitHub API"
L5 โ Missing "an" before "HTTP server" in mcp-server example comment
"# Run HTTP server on port 8080..." โ "# Run an HTTP server..."
L6 โ health CLI help omits token usage and costs
Docs mention "token usage, costs" as health outputs, but gh aw health --help doesn't list them. Fix: add the bullet or remove from docs.
L7 โ trial --append says "on installation" โ wrong context
trial is not an install command. Fix: change to "...before running" for trial.
L8 โ --auto-merge-prs wording differs between run and trial
run: "during the workflow execution" / trial: "during trial execution" โ trivial inconsistency; unify.
L9 โ --days allowed values not stated consistently
forecast --days: "(allowed values: 7, 30)" vs health --days: "(7, 30, or 90)" โ different constraints, different styles. Fix: both should clearly state allowed values in the same format.
L10 โ --timeout zero-value semantics inconsistent across 3 commands
forecast: "(0 disables timeout)" / trial: "(default 30)" / logs: "(0 = no timeout)" โ normalize zero-value documentation.
L11 โ --format default style inconsistent: audit vs logs
audit: flag annotation shows (default "pretty")
logs: prose "Default: compact agent-optimized output"
Fix: use consistent style across both.
L12 โ --output/-o default missing in outcomes
audit and logs both document (default ".github/aw/logs") but outcomes --output omits the default. Fix: add default annotation.
Metadata
| Item |
Value |
| Date |
2026-06-19 |
| Workflow run |
27830699006 |
| Docs file |
docs/src/content/docs/setup/cli.md |
| Method |
CLI --help collection + sub-agent analysis + manual diff |
Generated by โ
CLI Consistency Checker ยท 120.2 AIC ยท โ 7.75 AIC ยท โ 4.2K ยท โท
Summary
Automated CLI consistency inspection (2026-06-19) against the
gh-awbinary anddocs/src/content/docs/setup/cli.md. 34 commands inspected, 20 issues found.๐ด High
H1 โ
--dry-runsemantics differ betweenrunandtrialrun --dry-run:"Validate workflow without actually triggering execution on GitHub Actions"trial --dry-run:"Show what would be done without making any changes"trial --dry-runis broader (no changes at all) whilerun --dry-runonly skips dispatch. Users expect consistent semantics. Fix: align descriptions or renametrial's variant to--plan/--preview.๐ก Medium
M1 โ Missing article in
--appendflag (3 commands:add,deploy,trial)Text:
"Append extra content to the end of agentic workflow on installation"โ missing "the" before "agentic workflow".M2 โ Missing article in
trialhelp body"All workflows must support workflow_dispatch trigger to be used in trial mode."โ missing "the" before "workflow_dispatch trigger".M3 โ
--stdindescriptions differ betweenauditandlogsaudit:"...instead of positional arguments"logs:"...instead of discovering runs via the GitHub API"Same flag, different explanations. Fix: unify wording.
M4 โ
--dirdescription inconsistent:lintvs all others"Workflow directory (default: .github/workflows)"lint:"Directory to scan for *.lock.yml files when no arguments are provided (default \".github/workflows\")"Fix: normalize phrasing and default-value style.
M5 โ
--logical-reposhort flag-lonly ontrial, notcompileBoth commands have
--logical-repobut onlytrialexposes-l. Descriptions also diverge. Fix: add-ltocompileor remove it fromtrial; unify descriptions.M6 โ
--forcecovers three different behaviorsadd/deploy/new: overwrite filesupdate: force update even without changescompile: overwrite dependency files onlyFix: rename specialized variants (
--force-update,--force-deps) or add inline disambiguation.M7 โ
--verbosedocs vs CLI mismatch"Enable verbose output with debugging details""Enable verbose output showing detailed information"Fix: align both to the same wording.
๐ข Low (12 issues)
L1 โ "VSCode" โ "VS Code" in
inithelp"Configures VSCode settings (.vscode/settings.json)"โ incorrect brand capitalization.L2 โ Missing "the" before "expires field" in
inithelp"if any workflows use expires field for discussions or issues"โ"the expires field"L3 โ Awkward phrasing in
initCodespaces bullet"- Adds GitHub Copilot extensions and gh aw CLI installation"โ"...and installs the gh aw CLI"L4 โ Missing "the" before "GitHub API" in
compilehelp"resolving all action SHAs from GitHub API"โ"from the GitHub API"L5 โ Missing "an" before "HTTP server" in
mcp-serverexample comment"# Run HTTP server on port 8080..."โ"# Run an HTTP server..."L6 โ
healthCLI help omits token usage and costsDocs mention "token usage, costs" as health outputs, but
gh aw health --helpdoesn't list them. Fix: add the bullet or remove from docs.L7 โ
trial --appendsays "on installation" โ wrong contexttrialis not an install command. Fix: change to"...before running"fortrial.L8 โ
--auto-merge-prswording differs betweenrunandtrialrun:"during the workflow execution"/trial:"during trial execution"โ trivial inconsistency; unify.L9 โ
--daysallowed values not stated consistentlyforecast --days:"(allowed values: 7, 30)"vshealth --days:"(7, 30, or 90)"โ different constraints, different styles. Fix: both should clearly state allowed values in the same format.L10 โ
--timeoutzero-value semantics inconsistent across 3 commandsforecast:"(0 disables timeout)"/trial:"(default 30)"/logs:"(0 = no timeout)"โ normalize zero-value documentation.L11 โ
--formatdefault style inconsistent:auditvslogsaudit: flag annotation shows(default "pretty")logs: prose"Default: compact agent-optimized output"Fix: use consistent style across both.
L12 โ
--output/-odefault missing inoutcomesauditandlogsboth document(default ".github/aw/logs")butoutcomes --outputomits the default. Fix: add default annotation.Metadata
docs/src/content/docs/setup/cli.md--helpcollection + sub-agent analysis + manual diff