Skip to content

[cli-consistency] CLI Consistency Issues - 2026-04-17 #26877

@github-actions

Description

@github-actions

Summary

Automated CLI consistency inspection found 6 inconsistencies in command help text across the gh aw CLI. The most critical issue is a widespread incorrect --engine flag description that lists custom as a valid engine (it isn't) and omits gemini and crush (which are valid).

Breakdown by Severity

  • High: 2 (incorrect engine list causes user-facing errors)
  • Medium: 2 (confusing/misleading descriptions)
  • Low: 2 (minor wording inconsistencies)

Issue Categories

  1. Incorrect --engine flag values documented (10+ locations)

    • Documents custom as valid; it throws an error at runtime
    • Omits gemini and crush which ARE valid registered engines
    • Affects: compile, run, new, add, update, trial, validate, upgrade, init, completion, logs, mcp-server tool description
  2. add-wizard missing Gemini engine in description

    • Interactive wizard shows 4 engine options (including gemini) but description only lists 3
  3. health uses "Alerts" in description but "warnings" in flag (terminology drift)

  4. upgrade --no-fix overlap with --no-actions / --no-compile not explained

Inspection Details

  • Total Commands Inspected: 28 (all commands and subcommands with --help)
  • Commands with Issues: 14+
  • Date: 2026-04-17
  • Method: Executed all CLI commands with --help flags, cross-checked against engine registry source code, and validated with live ./gh-aw binary

Findings Summary

No issues found in these areas:

  • Flag naming conventions (-j/--json, -r/--repo, -e/--engine, -d/--dir used consistently)
  • Example syntax accuracy across all commands
  • --help / -h flags present on all commands
  • Documentation (docs/src/content/docs/setup/cli.md) covers all CLI commands
  • Short descriptions are concise and under 80 chars (no trailing periods)
  • Global flags (--banner, --verbose) consistent across all commands

⚠️ Issues found:

  • Engine list in --engine flag description (stale/wrong in 10+ locations)
  • Engine list in add-wizard long description
  • "Alerts" vs "warnings" in health command
  • project new Short description omits "board"
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).

Generated by CLI Consistency Checker · ● 4.7M ·

  • expires on Apr 19, 2026, 1:52 PM UTC

Metadata

Metadata

Labels

automationclicookieIssue Monster Loves Cookies!documentationImprovements or additions to documentation

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions