[cli-consistency] CLI Consistency Issues - 2026-06-09

[github-actions]

This issue tracks CLI documentation inconsistencies found during a comprehensive inspection of all gh aw commands.

Inspection method: Source code analysis (cmd/gh-aw/main.go, pkg/cli/*.go) cross-referenced against docs/src/content/docs/setup/cli.md.

Severity breakdown: 1 high · 7 medium · 4 low

---

High

H1 — mcp list-tools example shows wrong invocation syntax

Affected command: gh aw mcp

Docs (line 723):

gh aw mcp list-tools <mcp-server>          # List tools for server

Source (pkg/cli/mcp_list_tools.go):

Use:   "list-tools [workflow]",

The flag --server is required; <mcp-server> is not a positional argument.

Source examples (from Long text):

gh aw mcp list-tools --server github
gh aw mcp list-tools weekly-research --server github

Problem: The docs example implies mcp-server is a positional argument. A user following the docs literally (gh aw mcp list-tools github) will pass the value as a workflow name, not as the server filter, and either get the wrong results or an error about the missing required --server flag.

Suggested fix: Replace line 723 with the correct invocation:

gh aw mcp list-tools --server github           # List tools for a server (all workflows)
gh aw mcp list-tools workflow --server github  # List tools for a server in a specific workflow

---

Medium

M1–M7: Missing flag shorthands in docs (click to expand)

M1 — update: --dir, --force, --engine shorthands omitted

Docs (line 652):

**Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, ..., `--repo/-r`

Source (pkg/cli/update_command.go):

• --dir/-d, --force/-f, --engine/-e all have single-letter shorthands

Problem: --repo/-r is the only one listed with its shorthand; --dir, --force, --engine are not. Inconsistent within the same options list.

Suggested fix: Change --dir → --dir/-d, --force → --force/-f, --engine → --engine/-e.

---

M2 — new: --force shorthand omitted

Docs (line 209):

**Options:** `--force`, `--engine/-e`, `--interactive/-i`

Source (cmd/gh-aw/main.go):

• --force/-f registered via newCmd.Flags().BoolP("force", "f", ...)

Suggested fix: Change --force → --force/-f.

---

M3 — status: --json and --repo shorthands omitted

Docs (line 416):

**Options:** `--ref`, `--label`, `--json`, `--repo`

Source: addJSONFlag(cmd) → --json/-j; addRepoFlag(cmd) → --repo/-r

Suggested fix: Change --json → --json/-j and --repo → --repo/-r.

---

M4 — list: --json and --repo shorthands omitted

Docs (line 397):

**Options:** `--json`, `--label`, `--dir/-d`, `--path`, `--repo`

Source: addJSONFlag(cmd) → --json/-j; addRepoFlag(cmd) → --repo/-r

Suggested fix: Change --json → --json/-j and --repo → --repo/-r.

---

M5 — enable and disable: --repo shorthand omitted

Docs (lines 607, 620):

**Options:** `--repo`

(both commands)

Source (cmd/gh-aw/main.go): enableCmd.Flags().StringP("repo", "r", ...) and same for disableCmd

Suggested fix: Change --repo → --repo/-r in both enable and disable options lines.

---

M6 — health: --json and --repo shorthands omitted

Docs (line 558):

**Options:** `--days`, `--threshold`, `--repo`, `--json`

Source (pkg/cli/health_command.go): addJSONFlag(cmd) → --json/-j; addRepoFlag(cmd) → --repo/-r

Suggested fix: Change --json → --json/-j and --repo → --repo/-r.

---

M7 — forecast: --timeout flag not documented

Docs (line 592):

**Options:** `--days`, `--period`, `--sample`, `--eval`, `--repo/-r`, `--json/-j`

Source (pkg/cli/forecast_command.go):

cmd.Flags().Int("timeout", 0, "Gracefully stop forecast computation after this many minutes (0 disables timeout)")

Problem: --timeout is present in source but absent from docs options list. The source's own Long text includes an example:

gh aw forecast --timeout 10           # Stop gracefully after 10 minutes

Suggested fix: Add --timeout to the options list.

---

Low

L1–L4: Minor issues (click to expand)

L1 — init: .github/skills/agentic-workflow-designer/SKILL.md not documented

Source (pkg/cli/init_command.go Long text):

Creates the workflow designer skill at `.github/skills/agentic-workflow-designer/SKILL.md`

Docs: The init section describes the dispatcher skill (.github/skills/agentic-workflows/SKILL.md) and the agent file, but does not mention the agentic-workflow-designer skill.

Suggested fix: Add the designer skill file to the list of files created by init.

---

L2 — init: example comment mismatch

Source (pkg/cli/init_command.go line 73):

# Configure Codespaces for current repo only

Docs (cli.md line 143):

# Configure devcontainer for current repo only

Both describe gh aw init --codespaces "". The terminology differs ("Codespaces" vs "devcontainer").

Suggested fix: Align to the source wording: # Configure Codespaces for current repo only.

---

L3 — compile: --gh-aw-ref is not hidden but not documented

Source (cmd/gh-aw/main.go):

compileCmd.Flags().String("gh-aw-ref", "", "Convenience alias for --action-mode release --action-tag <ref>. Use this to E2E-test workflows...")

This flag has no MarkHidden call.

Docs: --gh-aw-ref does not appear in the compile options.

Problem: Undocumented non-hidden flags appear in --help output but have no docs entry, which is confusing. This appears to be an internal/E2E-testing flag that should be hidden.

Suggested fix: Add compileCmd.Flags().MarkHidden("gh-aw-ref") in main.go, or add a brief docs entry if intentionally public.

---

L4 — mcp-server: --port/-p shorthand omitted

Docs (line 748):

**Options:** `--port` (HTTP server port), ...

Source (pkg/cli/mcp_server_command.go):

cmd.Flags().IntVarP(&port, "port", "p", 0, "Port to run HTTP server on (uses stdio if not specified)")

Suggested fix: Change --port → --port/-p.

---

Inspection Metadata

Item	Detail
Commands inspected	init, new, add, add-wizard, remove, update, deploy, upgrade, compile, run, new, enable, disable, status, list, logs, audit, outcomes, checks, health, forecast, fix, lint, validate, mcp, mcp-server, secrets, env, pr, domains, completion, version
Docs file	docs/src/content/docs/setup/cli.md
Source files	cmd/gh-aw/main.go, pkg/cli/*.go
Date	2026-06-09
Method	Source code analysis (CLI binary build blocked by Go toolchain version mismatch)
Pre-collected help	/tmp/gh-aw/agent/all-help.txt was empty (pre-agent-steps did not populate it)

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 · ⌖ 13.3 AIC · ⊞ 15.6K · ◷

• expires on Jun 11, 2026, 6:13 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 · 20.5 AIC · ⌖ 8.88 AIC · ◷