[cli-consistency] CLI Consistency Issues - 2026-05-18

[github-actions]

Summary

Automated CLI consistency inspection found 5 inconsistencies across command help text and documentation that should be addressed for better user experience and documentation accuracy.

Breakdown by Severity

• High: 0 (Breaks functionality)
• Medium: 2 (Documentation gaps — commands/flags missing from docs)
• Low: 3 (Minor inconsistencies)

Issue Categories

1. Documentation gaps (2 issues)

   • gh aw outcomes command not documented in cli.md
   • --with-project-setup flag for gh aw project new not documented in cli.md

2. URL inconsistency (1 issue)

   • project_command.go help text references github.github.io but astro.config.mjs defines site as github.github.com

3. Minor text issues (2 issues)

   • Double spaces in gh aw forecast description (3 instances)
   • gh aw mcp-server description inconsistency between long description (mentions SSE) and examples (just say "HTTP server")

Inspection Details

• Total Commands Inspected: 32 (all main commands + subcommands with --help)
• Commands with Issues: 4
• Date: 2026-05-18
• Method: Executed all CLI commands with --help flags, compared against docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency (short flags -e, -r, -d, -j, -v, etc. are consistent)
• Command descriptions match their actual behavior
• Example accuracy and format consistency
• Terminology consistency ("workflow", "workflow-id", "agentic workflows")
• Global flags (--banner, --verbose) present on all commands

⚠️ Issues found:

• Documentation gaps (2 missing entries)
• URL mismatch (1 issue)
• Minor text quality issues (2 issues)

Detailed Findings

1. gh aw outcomes command not documented in cli.md

Priority: Medium
Type: Documentation gap

gh aw outcomes appears in gh aw --help under "Additional Commands" but has no entry in docs/src/content/docs/setup/cli.md.

Current CLI output (from ./gh-aw outcomes --help):

Evaluate the outcomes of safe output actions from a workflow run.

For each safe output (created issue, PR, comment, label, etc.), checks the current
state of the GitHub object to determine whether the action was accepted, rejected,
ignored, or is still pending.

This answers the question: "Did this workflow's actions actually help?"

Examples:
  gh aw outcomes 1234567890                # Check outcomes for a specific run
  gh aw outcomes 1234567890 --json         # JSON output
  gh aw outcomes 1234567890 --repo o/r     # Specify repository
  gh aw outcomes 1234567890 -v             # Verbose output

Issue: The command is available but undocumented in cli.md, making it hard to discover.

Suggested Fix: Add an #### outcomes section to the "Monitoring" or "Utility Commands" section of cli.md.

---

2. --with-project-setup flag not documented in cli.md

Priority: Medium
Type: Documentation gap — missing flag in docs

The gh aw project new CLI help shows a --with-project-setup flag, but it's absent from the project new section in docs/src/content/docs/setup/cli.md.

Current CLI output (from ./gh-aw project new --help):

  gh aw project new "Project Q1" --owner myorg --with-project-setup     # With project setup

Flags:
      --with-project-setup   Create standard project views and custom fields

Current docs (docs/src/content/docs/setup/cli.md lines 736-737):

**Options:**
- `--owner` (required): Project owner - use `@me` for current user or specify organization name
- `--link`: Repository to link project to (format: `owner/repo`)

Issue: The --with-project-setup flag is undocumented, so users won't know it creates standard views and custom fields.

Suggested Fix: Add --with-project-setup to the options list in the project new section.

---

3. URL mismatch in gh aw project new help text

Commands Affected: gh aw project new
Priority: Low
Type: URL inconsistency

Current help text (pkg/cli/project_command.go line 71):

See (github.github.io/redacted)

But docs/astro.config.mjs defines the docs site as:

site: 'https://github.github.com',
base: '/gh-aw/',

Issue: The URL in the CLI help uses github.github.io while the Astro config specifies github.github.com. One of these must be wrong. The correct GitHub Pages URL pattern for an org named github would be `(github.github.io/redacted)

Suggested Fix: Align astro.config.mjs to use (github.github.io/redacted) (which is the standard GitHub Pages URL format), or update project_command.go to use the correct URL.

---

4. Double spaces in gh aw forecast description

Commands Affected: gh aw forecast
Priority: Low
Type: Formatting/typo

Current help output (from ./gh-aw forecast --help):

per-run metrics (effective tokens, duration, success rate).  When runs have been
previously processed by 'gh aw logs', cached token-usage data is used.  The
...
P10–P90 confidence interval.  Use this to validate the model before relying on

Issue: Three instances of double spaces (sentence-end double-spacing) in the command description. While traditional in some typesetting, double spaces are inconsistent with the rest of the CLI help text.

Suggested Fix: Replace double spaces with single spaces in the three affected sentences in pkg/cli/forecast_command.go.

---

5. gh aw mcp-server description inconsistency (SSE mention)

Commands Affected: gh aw mcp-server
Priority: Low
Type: Inconsistency within help text

Current help text (from ./gh-aw mcp-server --help):

By default, the server uses stdio transport. Use the --port flag to run
an HTTP server with SSE (Server-Sent Events) transport instead.
...
gh aw mcp-server --port 8080   # Run HTTP server on port 8080 (for web-based clients)

Issue: The description calls it "SSE (Server-Sent Events) transport" but the example just says "HTTP server". The long description and examples are inconsistent in how they describe the non-stdio mode. Additionally, the MCP specification is moving toward Streamable HTTP as the preferred transport over SSE. The help text could clarify whether this is SSE or Streamable HTTP (or both).

Suggested Fix: Either align the example to say # Run HTTP/SSE server on port 8080 or update the description to say "Streamable HTTP/SSE transport" to reflect current MCP spec support.

Generated by ✅ CLI Consistency Checker · ● 20M · ◷

• expires on May 20, 2026, 2:27 PM UTC