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

[github-actions]

CLI Consistency Inspection — 2026-07-23

Commands/files inspected: All pkg/cli/*.go command files and docs/src/content/docs/setup/cli.md
Method: Static source analysis (pre-collected CLI help output was empty; source used directly)
Total issues found: 15

Severity Breakdown

Severity	Count
High	1
Medium	6
Low	8

---

High Severity

pr transfer command missing Options section in docs

• Affected command: pr transfer
• Location: docs/src/content/docs/setup/cli.md (~line 837)
• Quoted docs text: Section ends immediately after code block with no **Options:** entry
• Expected: **Options:** \--repo/-r``
• Priority: High — users cannot discover available flags

---

Medium Severity

6 medium severity findings

audit diff Short description does not indicate deprecation

• Affected command: audit diff subcommand
• Location: pkg/cli/audit_diff_command.go:21
• Quoted CLI output: Short: "Compare behavior across workflow runs"
• Issue: Long description immediately says "Deprecated: pass multiple run IDs directly to the audit command instead." but Short gives no hint of deprecation — users will continue using deprecated subcommand
• Suggested fix: "[Deprecated] Compare workflow runs (use: gh aw audit <id1> <id2>)"
• Priority: Medium

Root command branding may be stale

• Affected command: root gh aw --help
• Location: cmd/gh-aw/main.go:83
• Quoted CLI output: Short: "GitHub Agentic Workflows CLI from GitHub Next"
• Issue: "GitHub Next" was a research division; if the product has moved to a different org home, this branding is stale and confusing
• Suggested fix: "GitHub Agentic Workflows CLI" or update to current org branding
• Priority: Medium — verify current org structure first

-F shorthand deprecation message is self-referential

• Affected command: run
• Location: cmd/gh-aw/main.go:814
• Quoted source: MarkShorthandDeprecated("raw-field", "use --raw-field instead")
• Issue: Message tells users to "use --raw-field instead" — but -F IS the shorthand for --raw-field. The message is circular.
• Suggested fix: "use the long form --raw-field instead"
• Priority: Medium

--disable-X naming outlier

• Affected commands: fix, upgrade
• Issue: Codebase uses --no-X for negation flags throughout (e.g., --no-fix, --no-actions, --no-compile, --no-merge) but --disable-codemod does not follow this pattern.
• Note: --disable-codemod is repeatable and takes a value (ID), so --no-codemod is not a direct equivalent — but the naming is still inconsistent with the rest of the CLI.
• Priority: Medium — consider --skip-codemod or document the rationale

logs command Options list missing --evals

• Affected command: logs
• Location: docs/src/content/docs/setup/cli.md logs Options line
• Quoted source: logsCmd.Flags().Bool("evals", false, "Filter to runs containing evals results (evals.jsonl)...")
• Issue: --evals is implemented but absent from the logs Options list in docs; audit docs correctly include it
• Suggested fix: Add --evals between --end-date and --exclude-staged in the logs Options list
• Priority: Medium

secrets bootstrap missing -e short form in docs Options

• Affected command: secrets bootstrap
• Location: docs/src/content/docs/setup/cli.md (~line 268)
• Quoted source: cmd.Flags().StringVarP(&engineFlag, "engine", "e", ...)
• Issue: Docs list --engine without the -e short form that is implemented
• Suggested fix: --engine/-e in Options list
• Priority: Medium

---

Low Severity

8 low severity findings

lint Short description says "workflows" not "workflow files"

• Location: pkg/cli/lint_command.go:37
• Quoted text: "Lint existing .lock.yml workflows with actionlint only"
• Long text says: "workflow files from disk"
• Suggested fix: "Lint existing .lock.yml workflow files with actionlint only"

env get/env update have swapped adjective order

• Location: pkg/cli/env_command.go:137,174
• Issue: get → "Download default compiler variables" vs update → "Upload compiler default variables" — adjective order swapped between siblings
• Suggested fix: Normalize both to "compiler default variables"

mcp-server Short vs Long inconsistent phrasing

• Location: pkg/cli/mcp_server_command.go:22
• Short: "...exposing gh aw commands as tools" vs Long: "...that exposes gh aw CLI commands as MCP tools."
• Suggested fix: Align Short to use same relative-clause style as Long

--repo description varies across 4+ commands

• Location: flags.go:27, deploy_command.go:93, doctor_command.go:62, env_command.go:162
• Issue: doctor missing default note; env missing HOST/ in format spec; inconsistent "in" preposition placement
• Suggested fix: Standardize to canonical form: "Target repository ([HOST/]owner/repo format). Defaults to current repository"

validate defines --json inline instead of using AddJSONFlag helper

• Location: pkg/cli/validate_command.go:79
• Issue: Duplicates cmd.Flags().BoolP("json", "j", false, ...) instead of calling the AddJSONFlag(cmd) helper from flags.go; breaks single-source-of-truth
• Suggested fix: Replace with AddJSONFlag(cmd) call

deploy missing --pr alias present on all sibling commands

• Location: pkg/cli/deploy_command.go
• Issue: add, update, upgrade, init all have hidden --pr alias for --create-pull-request; deploy does not
• Suggested fix: Add hidden --pr alias to deploy

compile missing prose for --syft, --grype, --runner-guard

• Location: docs/src/content/docs/setup/cli.md compile section
• Issue: Flags appear in Options list but no explanatory prose; compare with --grant and --yamllint which have descriptions
• Suggested fix: Add brief callouts: --syft (SBOM scanner), --grype (vulnerability scanner), --runner-guard (taint analysis)

env Short says "GitHub variables" — ambiguous

• Location: pkg/cli/env_command.go:116
• Quoted text: "Manage compiler defaults as GitHub variables"
• Suggested fix: "Manage compiler defaults as GitHub Actions variables"

---

Inspection Metadata

Field	Value
Date	2026-07-23
Method	Static source analysis (pkg/cli/*.go + docs/src/content/docs/setup/cli.md)
Note	Pre-collected help output (/tmp/gh-aw/agent/all-help.txt) was empty (0 lines); source code used as primary input
Workflow run	30012333018

Warning

Firewall blocked 1 domain

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

• releaseassets.githubusercontent.com

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

network:
  allowed:
    - defaults
    - "releaseassets.githubusercontent.com"

See Network Configuration for more information.

Generated by ✅ CLI Consistency Checker · sonnet46 175.1 AIC · ⌖ 7.64 AIC · ⊞ 4.6K · ◷

• expires on Jul 25, 2026, 5:57 AM UTC-08:00

[github-actions]

🍪 Issue Monster selected this for Copilot

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

This looks self-contained to CLI/docs consistency work and should not conflict with the other selected issues in this batch.

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 · gpt54 2.84 AIC · ⌖ 6.63 AIC · ⊞ 6.8K · ◷