Summary
A comprehensive inspection of the gh aw CLI was performed on 2026-06-15. 8 issues were found: 4 medium and 4 low priority.
Commands inspected: add, add-wizard, audit, checks, compile, completion, deploy, disable, domains, enable, env (get/update), fix, forecast, hash-frontmatter, health, init, lint, list, logs, mcp, mcp-server, new, outcomes, pr, project, remove, run, secrets (set/bootstrap), status, trial, update, upgrade, validate, version (35+ total)
Severity Breakdown
| Severity |
Count |
| 🔴 High |
0 |
| 🟡 Medium |
4 |
| 🟢 Low |
4 |
| Total |
8 |
Medium Priority Issues
1. outcomes and version miscategorized in root --help
Affected commands: outcomes, version
outcomes and version appear under Additional Commands in gh aw --help instead of their logical sections (Analysis Commands and Utilities respectively).
Actual root --help output (relevant excerpt):
Analysis Commands:
audit Audit workflow runs and generate detailed reports
...
status Show status of all agentic workflows in the repository
Utilities:
completion Generate shell completion scripts
...
project Create GitHub Projects V2 boards
Additional Commands:
help Help about any command
outcomes Check what happened to a workflow run's safe outputs
version Print the current version
Expected: outcomes under Analysis Commands; version under Utilities.
Suggested fix: Register outcomes in the Analysis group and version in the Utilities group in the Cobra command configuration.
2. audit description too narrow in root help and docs
Affected: Root --help Common Tasks section; docs/src/content/docs/setup/cli.md Most Common Commands table
Root help Common Tasks (quoted):
gh aw audit <run-id-or-url> # Debug a failed run
Docs Most Common Commands table (quoted):
| [gh aw audit](#audit) | Debug a failed workflow run |
Actual gh aw audit --help description (quoted):
Audit one or more workflow runs by downloading artifacts and logs, detecting errors, analyzing MCP tool usage, and generating a concise report suitable for AI agents.
The command also supports multi-run diff mode and security analysis — not just debugging failed runs. The current description misleads users about the command's full capability.
Suggested fix:
- Root help:
gh aw audit <run-id-or-url> # Audit and analyze a workflow run
- Docs table:
Audit and analyze workflow runs (single or diff mode)
3. forecast terminology mismatch between docs and CLI
Affected command: forecast
CLI root --help (quoted):
forecast Forecast AI Credit usage and costs for agentic workflows (experimental)
CLI forecast --help (quoted):
[EXPERIMENTAL] Forecast AI Credit (AIC) usage for agentic workflows by sampling recent run history...
Docs cli.md forecast section (quoted):
Forecast token usage and costs for agentic workflows using recent run history and Monte Carlo simulation.
Docs use "token usage" while the CLI consistently uses "AI Credit (AIC) usage".
Suggested fix: Update the docs description to Forecast AI Credit (AIC) usage and costs for agentic workflows...
4. Misleading comment in logs example for --parse --json combination
Affected command: logs
Docs example (quoted):
gh aw logs --ref main --parse --json # With markdown/JSON output for branch
CLI --parse description (quoted): Run JavaScript parsers on agent logs and firewall logs, writing Markdown to log.md and firewall.md
CLI --json description (quoted): Output results in JSON format
The comment implies a single combined output, but --parse writes .md sidecar files while --json controls the stdout table format — these are independent operations.
Suggested fix:
gh aw logs --ref main --parse --json # Parse logs to markdown files + output JSON summary for branch
Low Priority Issues
Show 4 low-priority findings
5. status pattern filter not shown in documentation examples
CLI status --help (quoted):
Usage:
gh aw status [pattern] [flags]
Examples:
gh aw status ci- # Show workflows with 'ci-' in name
The docs examples only show flag-based filtering (--ref, --label, --repo) and never demonstrate the positional pattern argument. By contrast, list docs show gh aw list ci- # Filter by pattern (case-insensitive) prominently.
Suggested fix: Add gh aw status ci- # Filter by pattern (case-insensitive) to the docs examples for status.
6. health --days allowed values not documented
CLI health --help flag (quoted):
--days int Number of days to analyze (7, 30, or 90) (default 7)
Only three discrete values are accepted. This constraint is not mentioned in the docs. A user passing --days 14 would get an unexpected error.
Suggested fix: Document the constraint: --days accepts only 7, 30, or 90.
7. outcomes history subcommand not documented
gh aw outcomes history is functional but has no entry in cli.md.
CLI outcomes history --help (quoted):
Score recent issues and merged pull requests against the objective mapping.
Examples:
gh aw outcomes history
gh aw outcomes history --source issues --limit 100
gh aw outcomes history --repo owner/repo --json
Suggested fix: Add an outcomes history subsection under the outcomes command in the docs.
8. logs --cache-before terminology differs between docs and CLI
Docs (quoted): uses "cache cleanup", "Deletes cached run folders", comment text "Clean folders older than..."
CLI --cache-before flag description (quoted): (Cache eviction) Evict locally cached run folders for runs before this date, prior to downloading.
CLI example comments (quoted): "Evict local cache older than 1 week before downloading runs"
Suggested fix: Align docs to use "evict" / "cache eviction" terminology consistently with the CLI.
Inspection Metadata
| Field |
Value |
| Date |
2026-06-15 |
| Commands inspected |
35+ (all listed in root --help) |
| Source of truth |
Live CLI binary (./gh-aw --help) + docs/src/content/docs/setup/cli.md |
| Method |
--help output vs documentation cross-comparison |
| Workflow run |
27555991860 |
Generated by ✅ CLI Consistency Checker · 517.8 AIC · ⌖ 13.2 AIC · ⊞ 15.8K · ◷
Summary
A comprehensive inspection of the
gh awCLI was performed on 2026-06-15. 8 issues were found: 4 medium and 4 low priority.Commands inspected: add, add-wizard, audit, checks, compile, completion, deploy, disable, domains, enable, env (get/update), fix, forecast, hash-frontmatter, health, init, lint, list, logs, mcp, mcp-server, new, outcomes, pr, project, remove, run, secrets (set/bootstrap), status, trial, update, upgrade, validate, version (35+ total)
Severity Breakdown
Medium Priority Issues
1.
outcomesandversionmiscategorized in root--helpAffected commands:
outcomes,versionoutcomesandversionappear underAdditional Commandsingh aw --helpinstead of their logical sections (Analysis CommandsandUtilitiesrespectively).Actual root
--helpoutput (relevant excerpt):Expected:
outcomesunderAnalysis Commands;versionunderUtilities.Suggested fix: Register
outcomesin the Analysis group andversionin the Utilities group in the Cobra command configuration.2.
auditdescription too narrow in root help and docsAffected: Root
--helpCommon Tasks section;docs/src/content/docs/setup/cli.mdMost Common Commands tableRoot help Common Tasks (quoted):
Docs Most Common Commands table (quoted):
Actual
gh aw audit --helpdescription (quoted):The command also supports multi-run diff mode and security analysis — not just debugging failed runs. The current description misleads users about the command's full capability.
Suggested fix:
gh aw audit <run-id-or-url> # Audit and analyze a workflow runAudit and analyze workflow runs (single or diff mode)3.
forecastterminology mismatch between docs and CLIAffected command:
forecastCLI root
--help(quoted):CLI
forecast --help(quoted):Docs
cli.mdforecast section (quoted):Docs use "token usage" while the CLI consistently uses "AI Credit (AIC) usage".
Suggested fix: Update the docs description to
Forecast AI Credit (AIC) usage and costs for agentic workflows...4. Misleading comment in
logsexample for--parse --jsoncombinationAffected command:
logsDocs example (quoted):
gh aw logs --ref main --parse --json # With markdown/JSON output for branchCLI
--parsedescription (quoted):Run JavaScript parsers on agent logs and firewall logs, writing Markdown to log.md and firewall.mdCLI
--jsondescription (quoted):Output results in JSON formatThe comment implies a single combined output, but
--parsewrites.mdsidecar files while--jsoncontrols the stdout table format — these are independent operations.Suggested fix:
gh aw logs --ref main --parse --json # Parse logs to markdown files + output JSON summary for branchLow Priority Issues
Show 4 low-priority findings
5.
statuspattern filter not shown in documentation examplesCLI
status --help(quoted):The docs examples only show flag-based filtering (
--ref,--label,--repo) and never demonstrate the positional pattern argument. By contrast,listdocs showgh aw list ci- # Filter by pattern (case-insensitive)prominently.Suggested fix: Add
gh aw status ci- # Filter by pattern (case-insensitive)to the docs examples forstatus.6.
health --daysallowed values not documentedCLI
health --helpflag (quoted):Only three discrete values are accepted. This constraint is not mentioned in the docs. A user passing
--days 14would get an unexpected error.Suggested fix: Document the constraint:
--daysaccepts only 7, 30, or 90.7.
outcomes historysubcommand not documentedgh aw outcomes historyis functional but has no entry incli.md.CLI
outcomes history --help(quoted):Suggested fix: Add an
outcomes historysubsection under theoutcomescommand in the docs.8.
logs --cache-beforeterminology differs between docs and CLIDocs (quoted): uses "cache cleanup", "Deletes cached run folders", comment text "Clean folders older than..."
CLI
--cache-beforeflag description (quoted):(Cache eviction) Evict locally cached run folders for runs before this date, prior to downloading.CLI example comments (quoted): "Evict local cache older than 1 week before downloading runs"
Suggested fix: Align docs to use "evict" / "cache eviction" terminology consistently with the CLI.
Inspection Metadata
--help)./gh-aw --help) +docs/src/content/docs/setup/cli.md--helpoutput vs documentation cross-comparison