Detailed Findings
1. --engine flag lists wrong valid values (10+ locations)
Commands Affected: compile, run, new, add, update, trial, validate, upgrade, init, logs, completion
Priority: High
Type: Technical inaccuracy — causes user confusion and errors
Current Output (from running ./gh-aw compile --help):
-e, --engine string Override AI engine (claude, codex, copilot, custom)
Confirmed by running:
$ ./gh-aw compile --engine custom /tmp/x.md
✗ invalid engine value 'custom'. Must be 'claude', 'codex', 'copilot', 'crush', or 'gemini'
$ ./gh-aw new test --engine gemini
✓ Created new workflow: .github/workflows/test.md
Issue: The engine registry (pkg/workflow/agentic_engine.go) registers exactly 5 engines: claude, codex, copilot, gemini, crush. The value custom is not registered and raises a validation error when passed as a CLI flag. Yet all --engine flag descriptions across the codebase say (claude, codex, copilot, custom) — omitting gemini and crush.
Only secrets bootstrap is correct:
-e, --engine string Check tokens for specific engine (copilot, claude, codex, gemini, crush)
Affected source locations:
cmd/gh-aw/main.go lines 665, 669, 730
pkg/cli/flags.go lines 8, 14
pkg/cli/init_command.go line 120
pkg/cli/validate_command.go line 79
pkg/cli/completion_command.go line 23 (also in Long description text)
pkg/cli/mcp_tools_privileged.go line 37 (JSON schema comment)
pkg/cli/mcp_tools_readonly.go line 32 (inline comment)
Suggested Fix: Replace all occurrences of (claude, codex, copilot, custom) with (claude, codex, copilot, crush, gemini) in flag descriptions and inline comments. Optionally derive the list dynamically from workflow.GetGlobalEngineRegistry().GetSupportedEngines() to avoid future drift.
2. add-wizard Long description omits Gemini engine
Commands Affected: add-wizard
Priority: High
Type: Incomplete documentation — Gemini is a valid interactive option but not mentioned
Current Output (from running ./gh-aw add-wizard --help):
This command walks you through:
- Selecting an AI engine (Copilot, Claude, or Codex)
Issue: The interactive engine picker (pkg/cli/interactive.go lines 124–128) already shows 4 options: copilot, claude, codex, and gemini. The Long description omits Gemini. Additionally, the engine names use Title Case (Copilot, Claude, Codex) while CLI convention (and flag descriptions) use lowercase (copilot, claude, codex).
Suggested Fix:
- Selecting an AI engine (copilot, claude, codex, or gemini)
3. health command: "Alerts" in description vs "warnings" in flag
Commands Affected: health
Priority: Medium
Type: Terminology inconsistency
Current Output (from running ./gh-aw health --help):
Shows health metrics for workflows including:
...
- Alerts when success rate drops below threshold
...
--threshold float Success rate threshold for warnings (percentage) (default 80)
Issue: The body of the description says the command emits "Alerts" when below threshold, but the --threshold flag says it's a threshold for "warnings". The same concept is described with two different words.
Suggested Fix: Pick one term consistently — either change the description to say "Warnings when success rate drops below threshold" or change the flag description to say "Success rate threshold for alerts (percentage) (default 80)".
4. upgrade --no-fix description overlaps with --no-actions and --no-compile without explanation
Commands Affected: upgrade
Priority: Medium
Type: Confusing/misleading flag documentation
Current Output (from running ./gh-aw upgrade --help):
--no-fix Skip codemods, action version updates, and workflow compilation (only update agent files)
--no-actions Skip updating GitHub Actions versions
--no-compile Skip recompiling workflows (do not modify lock files)
Issue: --no-fix is described as skipping three things: codemods, action version updates, AND workflow compilation. But --no-actions and --no-compile also independently control the latter two. It's unclear whether these flags are additive or whether --no-fix is a superset. The relationship is not explained, which may lead users to believe --no-fix --no-actions skips all three steps but still compiles (because --no-compile wasn't passed).
Suggested Fix: Clarify in the --no-fix description that it is equivalent to --no-compile --no-actions plus skipping codemods. For example:
--no-fix Update agent files only: skip codemods, action version updates, and compilation (equivalent to --no-actions --no-compile plus skipping codemods)
5. project new Short description omits "board"
Commands Affected: project new
Priority: Low
Type: Minor description inconsistency
Current Output (from running ./gh-aw project new --help):
Create a new GitHub Project V2 board owned by a user or organization.
Issue: The Short description (pkg/cli/project_command.go) says "Create a new GitHub Project V2" but the Long description says "Create a new GitHub Project V2 board owned by a user or organization." The word "board" is missing from the Short description visible in command listings.
Suggested Fix: Update Short to "Create a new GitHub Project V2 board".
6. add-wizard engine names use inconsistent capitalization
Commands Affected: add-wizard
Priority: Low
Type: Style inconsistency
Issue: The add-wizard Long description uses Title Case for engine names: (Copilot, Claude, or Codex). All other commands and flag descriptions use lowercase: (claude, codex, copilot, custom). Engine IDs are always lowercase throughout the codebase.
Suggested Fix: Use lowercase: (copilot, claude, codex, or gemini) (combined with fix #2).
Summary
Automated CLI consistency inspection found 6 inconsistencies in command help text across the
gh awCLI. The most critical issue is a widespread incorrect--engineflag description that listscustomas a valid engine (it isn't) and omitsgeminiandcrush(which are valid).Breakdown by Severity
Issue Categories
Incorrect
--engineflag values documented (10+ locations)customas valid; it throws an error at runtimegeminiandcrushwhich ARE valid registered enginescompile,run,new,add,update,trial,validate,upgrade,init,completion,logs,mcp-servertool descriptionadd-wizardmissing Gemini engine in descriptiongemini) but description only lists 3healthuses "Alerts" in description but "warnings" in flag (terminology drift)upgrade --no-fixoverlap with--no-actions/--no-compilenot explainedInspection Details
--help)--helpflags, cross-checked against engine registry source code, and validated with live./gh-awbinaryFindings Summary
✅ No issues found in these areas:
-j/--json,-r/--repo,-e/--engine,-d/--dirused consistently)--help/-hflags present on all commandsdocs/src/content/docs/setup/cli.md) covers all CLI commands--banner,--verbose) consistent across all commands--engineflag description (stale/wrong in 10+ locations)add-wizardlong descriptionhealthcommandproject newShort description omits "board"Detailed Findings
1.
--engineflag lists wrong valid values (10+ locations)Commands Affected:
compile,run,new,add,update,trial,validate,upgrade,init,logs,completionPriority: High
Type: Technical inaccuracy — causes user confusion and errors
Current Output (from running
./gh-aw compile --help):Confirmed by running:
Issue: The engine registry (
pkg/workflow/agentic_engine.go) registers exactly 5 engines:claude,codex,copilot,gemini,crush. The valuecustomis not registered and raises a validation error when passed as a CLI flag. Yet all--engineflag descriptions across the codebase say(claude, codex, copilot, custom)— omittinggeminiandcrush.Only
secrets bootstrapis correct:Affected source locations:
cmd/gh-aw/main.golines 665, 669, 730pkg/cli/flags.golines 8, 14pkg/cli/init_command.goline 120pkg/cli/validate_command.goline 79pkg/cli/completion_command.goline 23 (also in Long description text)pkg/cli/mcp_tools_privileged.goline 37 (JSON schema comment)pkg/cli/mcp_tools_readonly.goline 32 (inline comment)Suggested Fix: Replace all occurrences of
(claude, codex, copilot, custom)with(claude, codex, copilot, crush, gemini)in flag descriptions and inline comments. Optionally derive the list dynamically fromworkflow.GetGlobalEngineRegistry().GetSupportedEngines()to avoid future drift.2.
add-wizardLong description omits Gemini engineCommands Affected:
add-wizardPriority: High
Type: Incomplete documentation — Gemini is a valid interactive option but not mentioned
Current Output (from running
./gh-aw add-wizard --help):Issue: The interactive engine picker (
pkg/cli/interactive.golines 124–128) already shows 4 options:copilot,claude,codex, andgemini. The Long description omits Gemini. Additionally, the engine names use Title Case (Copilot,Claude,Codex) while CLI convention (and flag descriptions) use lowercase (copilot,claude,codex).Suggested Fix:
3.
healthcommand: "Alerts" in description vs "warnings" in flagCommands Affected:
healthPriority: Medium
Type: Terminology inconsistency
Current Output (from running
./gh-aw health --help):Issue: The body of the description says the command emits "Alerts" when below threshold, but the
--thresholdflag says it's a threshold for "warnings". The same concept is described with two different words.Suggested Fix: Pick one term consistently — either change the description to say "Warnings when success rate drops below threshold" or change the flag description to say "Success rate threshold for alerts (percentage) (default 80)".
4.
upgrade --no-fixdescription overlaps with--no-actionsand--no-compilewithout explanationCommands Affected:
upgradePriority: Medium
Type: Confusing/misleading flag documentation
Current Output (from running
./gh-aw upgrade --help):Issue:
--no-fixis described as skipping three things: codemods, action version updates, AND workflow compilation. But--no-actionsand--no-compilealso independently control the latter two. It's unclear whether these flags are additive or whether--no-fixis a superset. The relationship is not explained, which may lead users to believe--no-fix --no-actionsskips all three steps but still compiles (because--no-compilewasn't passed).Suggested Fix: Clarify in the
--no-fixdescription that it is equivalent to--no-compile --no-actionsplus skipping codemods. For example:5.
project newShort description omits "board"Commands Affected:
project newPriority: Low
Type: Minor description inconsistency
Current Output (from running
./gh-aw project new --help):Issue: The
Shortdescription (pkg/cli/project_command.go) says "Create a new GitHub Project V2" but the Long description says "Create a new GitHub Project V2 board owned by a user or organization." The word "board" is missing from the Short description visible in command listings.Suggested Fix: Update Short to "Create a new GitHub Project V2 board".
6.
add-wizardengine names use inconsistent capitalizationCommands Affected:
add-wizardPriority: Low
Type: Style inconsistency
Issue: The
add-wizardLong description uses Title Case for engine names:(Copilot, Claude, or Codex). All other commands and flag descriptions use lowercase:(claude, codex, copilot, custom). Engine IDs are always lowercase throughout the codebase.Suggested Fix: Use lowercase:
(copilot, claude, codex, or gemini)(combined with fix #2).