[cli-consistency] CLI Consistency Issues - 2026-07-03

[github-actions]

Summary

Comprehensive inspection of the gh-aw CLI source code and documentation identified 12 issues across 4 categories. No critical bugs were found; all issues are consistency/quality improvements.

Severity breakdown:

• 🔴 High: 1
• 🟡 Medium: 4
• 🟢 Low: 7

---

🔴 High Severity

H1 — --no-models-dev-lookup missing from compile docs options list

Affected command: gh aw compile
Location: docs/src/content/docs/setup/cli.md:305 vs cmd/gh-aw/main.go:753

The compile command's Options list in the docs omits --no-models-dev-lookup, even though the flag is public (not hidden):

// cmd/gh-aw/main.go:753
compileCmd.Flags().Bool("no-models-dev-lookup", false,
    "Disable compile-time models.dev pricing lookup for models missing from the embedded catalog")

The current docs options line (cli.md:305) does not include this flag.

Expected: --no-models-dev-lookup should appear in the compile Options list in the documentation.

Suggested fix: Add --no-models-dev-lookup to the compile Options line at cli.md:305.

---

🟡 Medium Severity

4 medium-severity findings

M1 — env update command name/description mismatch

Affected command: gh aw env update
Location: pkg/cli/env_command.go:173–175

The command is named update but its Short and Long descriptions both say "Upload":

Use:   "update [file]",
Short: "Upload defaults from a YAML file",
Long:  `Upload compiler defaults from a YAML file.`

Its sibling env get correctly says "Download". The action is uploading, making the command name misleading.

Expected: Either rename the subcommand to upload (with update as a hidden alias for backward compatibility), or change Short/Long to say "Update defaults from a YAML file" if the intent is update semantics.

Priority: Medium — users may not immediately understand env update is an upload operation.

---

M2 — --no-Agentic-Workflows capitalization: missing "GitHub" prefix in init flag description

Affected command: gh aw init
Location: pkg/cli/init_command.go:145

The --no-agent flag description uses "Agentic Workflows" (capitalized as a product name) without the required "GitHub" prefix:

// line 145 — INCORRECT:
cmd.Flags().Bool("no-agent", false, "Skip creating the Agentic Workflows custom agent")

// line 146 — correct lowercase usage:
cmd.Flags().String("codespaces", "", "Create devcontainer.json for GitHub Codespaces with agentic workflows support...")

Per the project capitalization convention (encoded in cmd/gh-aw/capitalization_test.go): use "GitHub Agentic Workflows" for product-name references, or "agentic workflows" (lowercase) for generic references. The flag description uses neither form correctly.

Suggested fix: "Skip creating the GitHub Agentic Workflows custom agent" or "Skip creating the agentic workflows custom agent".

---

M3 — Deprecated aliases have no MarkDeprecated() call — users get no migration notice

Affected commands: gh aw add, gh aw update, gh aw trial, gh aw add-wizard
Locations: pkg/cli/add_command.go:197–199, pkg/cli/update_command.go:172–175, pkg/cli/trial_command.go:126–127, pkg/cli/add_wizard_command.go:118–120

Hidden deprecated flags are registered with MarkHidden() only — no MarkDeprecated() — so users who run old scripts receive no deprecation warning:

// Example from add_command.go:
cmd.Flags().Bool("no-security-scanner", false, "Disable security scanning ...")
cmd.Flags().Bool("disable-security-scanner", false, "Disable security scanning ...")
_ = cmd.Flags().MarkHidden("disable-security-scanner")  // hidden but no warning emitted!

Affected aliases:

Command	Deprecated alias	Canonical
add, update, trial	--disable-security-scanner	--no-security-scanner
update	--disable-release-bump	--no-release-bump
add-wizard	--skip-secret	--no-secret

Suggested fix: Add cmd.Flags().MarkDeprecated("disable-security-scanner", "use --no-security-scanner instead") (and similarly for the other aliases) so Cobra emits: Flag --disable-security-scanner has been deprecated, use --no-security-scanner instead.

---

M4 — engine names capitalized in add-wizard Long description but flag values are lowercase

Affected command: gh aw add-wizard
Location: pkg/cli/add_wizard_command.go:23 vs pkg/cli/flags.go:5

The Long description capitalizes engine names:

  - Selecting an AI engine (Copilot, Claude, Codex, Gemini, or Crush)

But the --engine flag requires lowercase values (e.g., --engine copilot). A user reading the Long description might try --engine Copilot (capitalized), which would fail validation.

Suggested fix: Change to " - Selecting an AI engine (copilot, claude, codex, gemini, or crush)" to match the actual accepted values.

---

🟢 Low Severity

7 low-severity findings

L1 — version command: Short says "Print", Long says "Show", docs use a third description

Location: cmd/gh-aw/main.go:494–495, docs/src/content/docs/setup/cli.md:813

Short: "Print the current version",
Long:  `Show the installed version of the gh aw extension.`,

Docs description: "Show gh-aw version and product information" — all three are different.

Suggested fix: Align all three to use the same verb and description. Recommend: Short → "Show the current version", Long → "Show the current version of the gh aw extension.", docs → "Show the current version".

---

L2 — deploy Long drops "agentic" qualifier from Short

Location: pkg/cli/deploy_command.go:30–31

Short: "Deploy agentic workflows to a target repository using a pull request",
Long:  `Deploy one or more workflows to a target repository by combining ...`

Short says "agentic workflows" but Long drops the qualifier to just "workflows".

Suggested fix: "Deploy one or more agentic workflows to a target repository by combining ...".

---

L3 — Docs use "gh-aw" (hyphen) for CLI invocations in mcp-server description

Location: docs/src/content/docs/setup/cli.md:780

Run MCP server exposing gh-aw commands as tools.

Source Short description uses "gh aw" (space — the correct CLI invocation form). Docs use "gh-aw" (hyphen — the extension/project name form). The description here refers to CLI commands, so "gh aw" (space) is correct.

Suggested fix: Change docs line 780 to "Run MCP server exposing gh aw commands as tools.".

---

L4 — mcp-server Short/Long verb inconsistency

Location: pkg/cli/mcp_server_command.go:22–23

Short: "Run an MCP (Model Context Protocol) server exposing gh aw commands as tools",
Long:  `Run an MCP server that exposes gh aw CLI commands as MCP tools.`

Short uses a participial phrase ("server exposing"), Long uses a relative clause ("server that exposes"). Additionally, "CLI" appears only in Long, not Short.

Suggested fix: Align the verb construction: Long: "Run an MCP (Model Context Protocol) server exposing gh aw CLI commands as tools.".

---

L5 — list Short/Long article inconsistency

Location: pkg/cli/list_workflows_command.go:32–33

Short: "List agentic workflows in the repository",
Long:  `List all agentic workflows in a repository without checking their status.`

Two inconsistencies: (1) Short says "in the repository" (definite — current repo) but Long says "in a repository" (indefinite — any repo); (2) Long adds "all" that Short lacks.

Suggested fix: Long: "List all agentic workflows in the repository without checking their status.".

---

L6 — British spelling "cancelled" in disable Long description

Location: cmd/gh-aw/main.go:213

Any in-progress runs will be cancelled before disabling.

American English spelling is "canceled" (one l). All other user-facing strings in the codebase use American English.

Suggested fix: "Any in-progress runs will be canceled before disabling."

---

L7 — --pre-releases (plural) on upgrade is non-standard

Location: pkg/cli/upgrade_command.go:163

cmd.Flags().Bool("pre-releases", false, "Include pre-release versions ...")

CLI convention (npm, pip, gh) uses singular --pre-release. The plural form is technically accurate but unusual.

Suggested fix (optional): Rename to --pre-release with --pre-releases kept as a hidden alias. Docs at cli.md:718 already reflect the current plural form correctly.

---

Inspection Metadata

Field	Value
Date	2026-07-03
Commands inspected	38 (all registered in cmd/gh-aw/main.go)
Source files analyzed	cmd/gh-aw/main.go, all pkg/cli/*_command.go files
Docs file analyzed	docs/src/content/docs/setup/cli.md
Method	Source code analysis (binary unavailable; all-help.txt was empty)
Total issues found	12
High: 1 / Medium: 4 / Low: 7

Commands Inspected (38 total)

init, add-wizard, add, new, secrets (set, bootstrap), fix, compile, validate, lint, trial, run, list, status, logs, audit (diff), outcomes (history), health, checks, forecast, enable, disable, remove, update, deploy, upgrade, env (get, update), mcp (list, list-tools, inspect, add), pr transfer, mcp-server, domains, version, completion, project (new), hash-frontmatter

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · 852.9 AIC · ⌖ 13 AIC · ⊞ 4.5K · ◷

• expires on Jul 5, 2026, 6:02 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · 1.4 AIC · ⌖ 4.89 AIC · ⊞ 6.5K · ◷