Repository navigation
Description
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/-eall 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/-fregistered vianewCmd.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.allowedlist 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
Activity
github-actions commentedon Jun 9, 2026
🍪 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! 🍪
[docs] Fix CLI flag shorthands and init description in cli.md
docs(cli): align init/forecast wording with CLI source-of-truth