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

[github-actions]

Summary

This issue tracks CLI consistency problems identified by automated inspection of command help text, flag definitions, and documentation (docs/src/content/docs/setup/cli.md).

Severity	Count
High	3
Medium	11
Low	7
Total	21

Inspection scope: All commands in cmd/gh-aw/main.go + all pkg/cli/*_command.go files + docs/src/content/docs/setup/cli.md
Date: 2026-07-15
Method: Static analysis of source + documentation cross-reference

---

High Severity

H1 — run command Example uses hardcoded gh aw string

Affected command: run
Location: cmd/gh-aw/main.go:428
Quoted CLI source:

Example: `  gh aw run                          # Interactive mode
  gh aw run daily-perf-improver

Issue: Every other command in main.go constructs its Example field using string(constants.CLIExtensionPrefix) + " run ..." (e.g., newCmd line 127, compileCmd line 274, versionCmd line 499). runCmd is the only command that hardcodes the "gh aw" prefix as a string literal. If the CLI prefix constant ever changes, runCmd examples will not update.

Suggested fix: Replace the runCmd.Example literal with string(constants.CLIExtensionPrefix) concatenations matching the pattern used by all other commands.

---

H2 — Mixed indentation in rootCmd.Long (tab vs spaces)

Affected command: root
Location: cmd/gh-aw/main.go:89
Quoted CLI source:

  gh aw init                  \t\t# Set up a new repository
\tgh aw doctor --repo owner/repo \t\t# Run diagnostics for authentication and repository setup
  gh aw add-wizard            \t\t# Add workflows with interactive guided setup

Issue: The doctor line starts with a hard tab \t while every other Common Tasks entry uses two leading spaces. This breaks visual column alignment in all terminals (tab width varies). The status entry (line 94) also has one fewer space than its peers.

Suggested fix:

• Line 89: Replace leading \t with two spaces: gh aw doctor --repo owner/repo
• Line 94: Pad to align: gh aw status \t\t# Check workflow status

---

H3 — doctor command missing from docs

Affected command: doctor
Location: docs/src/content/docs/setup/cli.md (no section exists)
CLI source: pkg/cli/doctor_command.go — command is not hidden
Issue: gh aw doctor is a visible, user-facing command (grouped under Setup Commands, listed in rootCmd.Long Common Tasks) but has no corresponding section in cli.md. Users consulting the docs will not find documentation for it.

Suggested fix: Add a #### \gh aw doctor`section under Setup Commands incli.mddocumenting its purpose, the--repo` flag, and example usage.

---

Medium Severity (11 issues)

M1 — rootCmd Short/Long header inconsistency

Location: cmd/gh-aw/main.go:83,85
Issue: Short says "GitHub Agentic Workflows CLI from GitHub Next" but Long header says "GitHub Agentic Workflows from GitHub Next" — 'CLI' is missing from Long.
Suggested fix: Change Long header to match Short: "GitHub Agentic Workflows CLI from GitHub Next"

---

M2 — versionCmd Short/Long/docs triple mismatch

Location: cmd/gh-aw/main.go:497-498, docs/src/content/docs/setup/cli.md
Quoted text:

• Short: "Print the current version"
• Long: "Show the installed version of the gh aw extension."
• Docs: "Show gh-aw version and product information."

Issue: Three different formulations for the same command across Short, Long, and docs.
Suggested fix: Standardize to: Short "Print the current version", Long "Print the current version and build information for the gh aw CLI extension."

---

M3 — disableCmd.Long uses British spelling cancelled

Location: cmd/gh-aw/main.go:214
Quoted text: "Any in-progress runs will be cancelled before disabling."
Issue: The rest of the codebase (e.g., pkg/cli/org_runner.go, pkg/cli/actionlint.go) uses American "canceled". This is the only occurrence of the British form.
Suggested fix: "Any in-progress runs will be canceled before disabling."

---

M4 — compileCmd example comment misleading for --gh-aw-ref main

Location: cmd/gh-aw/main.go:284
Quoted text: gh aw compile --gh-aw-ref main # Pin workflows to current HEAD of github/gh-aw main
Issue: The --gh-aw-ref flag resolves the branch to its commit SHA at compile time, producing an immutable pin. The comment "current HEAD" implies the pin tracks the live branch, which is the opposite of the flag's purpose.
Suggested fix: # Pin workflows to the SHA of github/gh-aw main at compile time

---

M5 — compileCmd.Long uses single-quoted 'upgrade' instead of backtick command path

Location: cmd/gh-aw/main.go:250
Quoted text: "Unlike 'upgrade', compilation only applies codemods when you opt in with --fix."
Issue: Uses single-quotes for a command name; every other command reference in docs and Long descriptions uses backtick-quoted full paths (e.g., `gh aw upgrade`).
Suggested fix: "Unlike `gh aw upgrade`, `gh aw compile` only applies codemods when you opt in with `--fix`."

---

M6 — --dependabot bullet points have inconsistent grammatical structure

Location: cmd/gh-aw/main.go:238-243, compileCmd.Long
Quoted text:

  - For npm: Creates package.json and package-lock.json (requires npm in PATH)
  - For Python: Creates requirements.txt for pip packages
  - For Go: Creates go.mod for go install/get packages
  - Creates .github/dependabot.yml with all detected ecosystems

Issue: First three bullets have a "For X:" prefix; the fourth does not.
Suggested fix: " - Generates .github/dependabot.yml with entries for all detected ecosystems"

---

M7 — run --approve description copy-pasted from compile --approve

Location: cmd/gh-aw/main.go:804 (run), cmd/gh-aw/main.go:757 (compile)
Issue: Identical long descriptions on both commands, but run --approve applies only during the auto-recompile triggered by --push. The compile-centric description is confusing in the run context.
Suggested fix (run only): "Approve safe-update manifest changes when --push triggers an automatic recompile step"

---

M8 — --engine flag description hardcoded and duplicated across 5+ commands

Location: cmd/gh-aw/main.go:719,723,796, pkg/cli/add_command.go, pkg/cli/trial_command.go, etc.
Issue: "Override AI engine (copilot, claude, codex, gemini, antigravity, opencode, pi)" is copy-pasted verbatim. Adding a new engine requires updating all copies.
Suggested fix: Define EngineFlagUsage as a package-level constant in pkg/cli and reference it from all flag registrations.

---

M9 — run --raw-field description says "parameter" not "input"

Location: cmd/gh-aw/main.go:800
Quoted text: "Add a string parameter in key=value format (can be used multiple times)"
Issue: These are GitHub Actions workflow dispatch inputs, not generic "parameters". Mismatches gh workflow run -F documentation and GitHub Actions terminology.
Suggested fix: "Pass a workflow dispatch input in key=value format (can be specified multiple times)"

---

M10 — fix command Short mismatches docs description

Location: pkg/cli/fix_command.go:39, docs/src/content/docs/setup/cli.md fix section
Quoted text:

• CLI Short: "Apply automatic codemod-style fixes to agentic workflow files"
• Docs: "Auto-fix deprecated workflow fields using codemods. Runs in dry-run mode by default; use \--write` to apply changes." **Issue:**"codemod-style fixes"is imprecise; these *are* codemods. The docs description is clearer and includes the importantdry-run by defaultbehavior. **Suggested fix:**"Auto-fix deprecated agentic workflow fields using codemods (dry-run by default)"`

---

M11 — run example comment differs from docs for --push

Location: cmd/gh-aw/main.go:436, docs/src/content/docs/setup/cli.md run section
Quoted text:

• CLI Example: gh aw run daily-perf-improver --push # Commit and push workflow files before running
• Docs: gh aw run workflow --push # Auto-commit, push, and dispatch workflow
  Issue: The CLI example says "Commit and push ... before running" while docs say "Auto-commit, push, and dispatch" — the dispatch is implicit in both but explicitly called out only in docs.
  Suggested fix: Align both to: # Commit, push, and dispatch the workflow

Low Severity (7 issues)

L1 — project command Short missing "and manage"

Location: pkg/cli/project_command.go:38
CLI Short: "Create GitHub Projects V2 boards"
Docs: "Create and manage GitHub Projects V2 boards."
Suggested fix: Add "and manage" to the CLI Short.

---

L2 — experiments command Short is vague

Location: pkg/cli/experiments_command.go:92
Quoted text: "Explore ongoing experiments in the repository"
Issue: "Explore" doesn't indicate the primary action (listing). "Ongoing" implies only running experiments.
Suggested fix: "List and analyze experiment workflow branches in the repository"

---

L3 — env get Short ambiguous ("defaults")

Location: pkg/cli/env_command.go:137
Quoted text: "Download defaults into a YAML file"
Issue: "defaults" is ambiguous without context; Long says "default compiler variables".
Suggested fix: "Download default compiler variables into a YAML file"

---

L4 — env update Short ambiguous ("defaults")

Location: pkg/cli/env_command.go:174
Quoted text: "Upload defaults from a YAML file"
Suggested fix: "Upload default compiler variables from a YAML file"

---

L5 — secrets bootstrap Short imprecise

Location: pkg/cli/tokens_bootstrap.go:22
Quoted text: "Analyze workflows and set up required secrets"
Issue: "Set up" is vague. The command prompts interactively.
Suggested fix: "Analyze workflows and interactively configure required secrets"

---

L6 — compile --show-all hardcodes "top five" in description

Location: cmd/gh-aw/main.go:751
Quoted text: "Display all prioritized compilation errors instead of the default top five"
Issue: Hard-coded "top five" will become stale if the default cap changes.
Suggested fix: "Display all compilation errors instead of only the highest-priority subset (default: top 5)"

---

L7 — --action-tag description ambiguous about tag name resolution

Location: cmd/gh-aw/main.go:725 (flag description) vs compileCmd.Long:262-265 (inline docs)
Issue: Flag description says "Cannot be combined with --gh-aw-ref; use --gh-aw-ref when you want to resolve a branch or tag name to its current SHA" but the Long text says "branch names are not resolved". Ambiguity: are tag names resolved or not?
Suggested fix: Clarify in Long: "The value is used verbatim; neither branch names nor tag names are resolved to their commit SHA. Use --gh-aw-ref to resolve a branch or tag at compile time."

---

Inspection Metadata

Field	Value
Date	2026-07-15
Commands inspected	compile, run, new, remove, enable, disable, version, add, add-wizard, init, update, status, logs, audit, fix, upgrade, validate, doctor, mcp, list, view, bootstrap, trial, deploy, secrets, project, env, experiments, forecast, domains, lint, checks, outcomes, health, pr, hash, completion (all non-hidden + hidden sampled)
Total issues	21
Source files	cmd/gh-aw/main.go, pkg/cli/*_command.go, docs/src/content/docs/setup/cli.md
Method	Static source analysis + docs cross-reference

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• proxy.golang.org
• releaseassets.githubusercontent.com

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

network:
  allowed:
    - defaults
    - "proxy.golang.org"
    - "releaseassets.githubusercontent.com"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · 218.7 AIC · ⌖ 15.2 AIC · ⊞ 4.4K · ◷

• expires on Jul 17, 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.54 AIC · ⌖ 4.75 AIC · ⊞ 3.6K · ◷