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