[cli-consistency] CLI Consistency Issues - 2026-07-08 #44309

M1 — github/claude lowercase in root command Long description

File: cmd/gh-aw/main.go line 122
Exact quote: "...github repositories...", "...claude..." (lowercase)
Fix: Capitalize to "GitHub" and "Claude".

M2 — version command: "Print" vs "Show" inconsistency

File: cmd/gh-aw/main.go lines 494–495
Short: "Print the current version"
Long: "Show the installed version..."
Fix: Standardize to one verb. Prefer "Show" to match Long, or "Print" throughout.

M3 — upgrade Short missing articles

File: pkg/cli/upgrade_command.go
Exact quote: "Upgrade repository with latest agent files..."
Fix: "Upgrade the repository with the latest agent files..."

M4 — Single quotes used instead of backticks for inline command references (7+ instances)

Files: add_command.go, add_wizard_command.go, update_command.go, upgrade_command.go

Examples:

• "...run 'gh aw add wizard' instead" → should use backtick fences `gh aw add wizard`
• "...use 'gh aw update' to update..." → `gh aw update`

All cross-command references in Long descriptions use single quotes '...' instead of backtick code spans. Terminal renderers and docs sites format these differently.

Fix: Replace all 'gh aw ...' with `gh aw ...` in Long descriptions.

M5 — --no-secret/--skip-secret hidden alias has no deprecation warning

Files: pkg/cli/add_command.go:~185, add_wizard_command.go:123-125
Both --no-secret and --skip-secret are registered; --skip-secret is hidden but not deprecated.
Fix: _ = cmd.Flags().MarkDeprecated("skip-secret", "use --no-secret instead")

M6 — --pr hidden alias for --create-pull-request in four commands

Files: add_command.go:174-176, update_command.go:182-186, upgrade_command.go:158-159, init_command.go:149-150
The --pr alias works silently but is undocumented. It conflicts with the conventional meaning of --pr in other GitHub CLIs (pull request number).
Fix: Apply MarkDeprecated("pr", "use --create-pull-request instead") across all four, or promote it to a visible named alias.

M7 — --format default empty string in logs vs "pretty" in audit/audit diff

Files: pkg/cli/logs_command.go:376 vs audit.go:107
Same flag, same valid values (pretty, markdown), but logs defaults to "" while audit defaults to "pretty".
Fix: Set --format default to "pretty" in logs_command.go, or document why an explicit format is required.

M8 — --count/--last in logs vs --limit in outcomes history — same concept, different names

Files: pkg/cli/logs_command.go:356, outcomes_history.go:111
Fix: Standardize on --limit. Apply MarkDeprecated on --count and hide/deprecate --last.

M9 — --output vs --outcomes-dir confusingly similar names in outcomes command

File: pkg/cli/outcomes_command.go:42-43,64
--output = artifact output directory; --outcomes-dir = OTLP export directory. Both are *-dir-style paths for different things in the same command.
Fix: Rename --outcomes-dir to --otlp-dir or --export-dir.

M10 — --firewall and --no-firewall can be passed simultaneously (no mutual exclusion)

File: pkg/cli/logs_command.go:367-368
Both are independent Bool flags with no MarkFlagsMutuallyExclusive. Passing both is silently accepted.
Fix: _ = cmd.MarkFlagsMutuallyExclusive("firewall", "no-firewall")

M11 — --stop-after and --no-stop-after can be passed simultaneously (no mutual exclusion)

Files: add_command.go, add_wizard_command.go:117-120, deploy_command.go:100-101, update_command.go
Complementary flags with no enforcement; passing both is nonsensical but accepted silently.
Fix: _ = cmd.MarkFlagsMutuallyExclusive("stop-after", "no-stop-after") in each affected command.

M12 — lint and fix missing --json flag

Files: pkg/cli/lint_command.go:79-81, fix_command.go:83-86
Sibling commands validate, compile, audit all have --json. lint produces actionlint/shellcheck diagnostics that CI tools need to parse; fix --list-codemods lists codemods — both are prime candidates for JSON output.
Fix: Add addJSONFlag(cmd) to both command setup functions.

M13 — fix and upgrade missing --dry-run flag

Files: pkg/cli/fix_command.go, upgrade_command.go
run and env delete have --dry-run. fix modifies workflow files; upgrade modifies workflow files, lock files, and manifests. Neither has a preview mode.
Fix: Add --dry-run to both. For fix, it is an explicit alias for the default no---write mode. For upgrade, expose --audit as an alias or add a distinct --dry-run.

M14 — "PRs" vs "pull requests" in outcomes history

File: pkg/cli/outcomes_history.go
Short: "...PRs..."
Long: "...pull requests..."
Fix: Use "pull requests" consistently throughout.

L1 — "detected shell" vs "current shell" in completion install/uninstall

File: pkg/cli/completion_command.go
Install Short: "detected shell", Long: "current shell". Uninstall has same inconsistency.
Fix: Standardize to "current shell".

L2 — pr_command Short has no imperative verb

File: pkg/cli/pr_command.go
Short: "Pull request utilities" (noun phrase)
All other commands use an imperative verb: "Add", "Compile", "Run", etc.
Fix: "Manage pull request utilities" or "Work with pull request utilities".

L3 — deploy Long omits "agentic" present in Short

File: pkg/cli/deploy_command.go
Short includes "agentic", Long first sentence drops it.
Fix: Keep "agentic" in Long first sentence for consistency.

L4 — lint Short says "workflows", Long says "workflow files"

File: pkg/cli/lint_command.go
Fix: Standardize to "workflow files" throughout.

L5 — workflow(s) parenthetical-s notation in trial

File: pkg/cli/trial_command.go
"workflow(s)" notation is inconsistent with all other commands which use plain "workflows" or "workflow".
Fix: Use "one or more workflows" or simply "workflows".

L6 — list Short: "the repository" (definite) vs Long: "a repository" (indefinite)

File: pkg/cli/list_workflows_command.go
Short: "...workflows in the repository" → Long: "...workflows in a repository"
Fix: Standardize to "the current repository" in both.

L7 — env Short description is ambiguous

File: pkg/cli/env_command.go
Short: "Manage compiler defaults as GitHub variables" — unclear whether it manages GitHub Actions variables OR uses variables as a storage backend.
Fix: "Manage compiler default settings stored as GitHub variables".

L8 — init Long has non-parallel bullet structure

File: pkg/cli/init_command.go
One bullet is a declarative sentence; others are imperative. Makes the list feel inconsistent when rendered.
Fix: Rewrite all bullets in the same grammatical form.

L9 — --validate vs --validate-images inconsistent naming level in compile

File: cmd/gh-aw/main.go:722,752
--validate bundles schema + image + action checks. --validate-images is a stricter sub-check of the image part. The names suggest they're peers, but they're not.
Fix: Rename --validate-images to --require-docker or --strict-image-validation.

L10 — --mcp hidden in init has no MarkDeprecated

File: pkg/cli/init_command.go:143,151-153
--mcp is MarkHidden but not MarkDeprecated; users passing it get no migration guidance.
Fix: _ = cmd.Flags().MarkDeprecated("mcp", "MCP is now enabled by default; use --no-mcp to disable")

L11 — --days default inconsistency: health defaults to 7, forecast to 30

Files: pkg/cli/health_command.go:82, forecast_command.go:107
Same flag, same concept, different undocumented defaults. Users running both without reading docs get results for different windows.
Fix: Explicitly call out the default window in both commands' help text.

L12 — --last is a visible alias for --count in logs

File: pkg/cli/logs_command.go:378
Two documented names for the same flag. Most other aliases are hidden.
Fix: Apply MarkHidden("last") + MarkDeprecated to guide users to --count (or --limit per M8).

L13 — add wizard missing --repo and --create-pull-request vs add

Files: pkg/cli/add_wizard_command.go, add_command.go
The wizard is an interactive frontend to add but lacks --repo (target remote repo) and --create-pull-request. If intentional, the wizard's --help should say it only operates on the current local repository.
Fix: Add --repo + --create-pull-request to add wizard, or document the local-only restriction explicitly.