Detailed Findings
1. gh aw init — Embedded "Usage:" Creates Duplicate Section in Help Output
Commands Affected: init
Priority: Medium
Type: Structural bug in help text
Current Output (from running ./gh-aw init --help):
Initialize the repository for agentic workflows by configuring .gitattributes and creating the dispatcher agent file.
Usage:
gh aw init
This command performs non-interactive repository setup...
...
Usage:
gh aw init [flags]
Flags:
...
Issue: The Long description in pkg/cli/init_command.go (lines 18–21) contains a literal Usage:\n gh aw init block inside the Go string. Cobra renders the Long description verbatim, then appends its own generated Usage: block — resulting in two "Usage:" sections in the final --help output. This is unique to init; no other command has this issue.
Suggested Fix: Remove the embedded Usage: block from the Long description. The information is redundant since Cobra generates the Usage section automatically.
// Before
Long: `Initialize the repository for agentic workflows by configuring .gitattributes and creating the dispatcher agent file.
Usage:
gh aw init
This command performs non-interactive repository setup...`
// After
Long: `Initialize the repository for agentic workflows by configuring .gitattributes and creating the dispatcher agent file.
This command performs non-interactive repository setup...`
2. gh aw trial --clone-repo — "Alternative to --logical-repo" Is Misleading
Commands Affected: trial
Priority: Medium
Type: Inaccurate flag description
Current Output (from running ./gh-aw trial --help, Flags section):
--clone-repo string Alternative to --logical-repo: clone the contents of the specified repo into the host repo instead of using logical repository simulation
Issue: The description calls --clone-repo an "alternative to --logical-repo", but the Repository modes section in the same help text makes clear they do fundamentally different things:
--logical-repo REPO — changes the github.repository context (simulates execution as if installed in REPO)--clone-repo REPO — copies REPO's file contents into the trial repository before execution
These are not mutually exclusive alternatives; they address different needs. A user might legitimately use both. Describing one as an "alternative" to the other will cause confusion.
Suggested Fix: Update the flag description to accurately describe what --clone-repo does without framing it as an alternative:
--clone-repo string Clone the contents of the specified repo into the host repo before execution (useful for testing against actual repository state)
3. gh aw mcp add --transport — Inconsistent Capitalization of Transport Type Values
Commands Affected: mcp add, mcp inspect
Priority: Low
Type: Capitalization inconsistency
Current Output (from running ./gh-aw mcp add --help):
--transport string Preferred transport type (stdio, http, docker)
Current Output (from running ./gh-aw mcp inspect --help):
This command starts each MCP server configured in the workflow, queries its capabilities,
and displays the results in a formatted table. It supports stdio, Docker, and HTTP MCP servers.
Issue: mcp add lists transport types as all-lowercase stdio, http, docker, while mcp inspect uses Docker and HTTP with standard capitalization. The values listed in mcp add are likely intended as the literal flag values (where case matters), but the inconsistency across the two commands creates visual confusion.
Suggested Fix: Use consistent casing. Since these are literal flag values the user must type, lowercase is appropriate for the mcp add flag description. Update mcp inspect prose to use lowercase consistently:
It supports stdio, docker, and http MCP servers.
4. gh aw logs --safe-output — Examples Omit Valid Safe-Output Types
Commands Affected: logs
Priority: Low
Type: Incomplete documentation
Current Output (from running ./gh-aw logs --help):
--safe-output string Filter to runs containing a specific safe output type (e.g., create-issue, missing-tool, missing-data)
Issue: The examples and flag description only mention three safe-output types. Inspecting pkg/workflow/js/safe_outputs_tools.json shows that noop and report-incomplete are also valid tool names produced by workflows. A user trying to filter for noop completions or report-incomplete failures would not discover these types from the help text.
Suggested Fix: Expand the example list to include the most commonly used types:
--safe-output string Filter to runs containing a specific safe output type (e.g., create-issue, missing-tool, missing-data, noop, report-incomplete)
Summary
Automated CLI consistency inspection found 4 inconsistencies across command help text that should be addressed for better user experience.
Breakdown by Severity
Issue Categories
inithasUsage:embedded inside the Long description, producing a confusing duplicate Usage sectiontrial --clone-repodescribes itself as "Alternative to --logical-repo" but the two flags serve fundamentally different purposesmcp add --transportlists values asstdio, http, dockerwhilemcp inspectprose usesDockerandHTTPlogs --safe-outputonly examplescreate-issue,missing-tool,missing-data; omits valid valuesnoopandreport-incompleteInspection Details
--helprun for every top-level command and all subcommands: add, add-wizard, audit, audit diff, checks, compile, completion, disable, domains, enable, fix, hash-frontmatter, health, init, list, logs, mcp, mcp add, mcp inspect, mcp list, mcp list-tools, mcp-server, new, pr, pr transfer, project, project new, remove, run, secrets, secrets bootstrap, secrets set, status, trial, update, upgrade, validate, version)make build, executed all CLI commands with--helpflags, reviewed source code for each findingFindings Summary
✅ No issues found in these areas:
-h,-v,-e,-r,-j,-d,-fused consistently)# commentstyle throughout)--repeatdescription consistent acrossrunandtrial--approvedescription consistent acrosscompile,run, andupgradedocs/src/content/docs/setup/cli.mdmatches CLI commandsUsage:ininitLong description--clone-repoflag description intrialmcp add --transportvalues--safe-outputexamples inlogsDetailed Findings
1.
gh aw init— Embedded "Usage:" Creates Duplicate Section in Help OutputCommands Affected:
initPriority: Medium
Type: Structural bug in help text
Current Output (from running
./gh-aw init --help):Issue: The Long description in
pkg/cli/init_command.go(lines 18–21) contains a literalUsage:\n gh aw initblock inside the Go string. Cobra renders the Long description verbatim, then appends its own generatedUsage:block — resulting in two "Usage:" sections in the final--helpoutput. This is unique toinit; no other command has this issue.Suggested Fix: Remove the embedded
Usage:block from the Long description. The information is redundant since Cobra generates the Usage section automatically.2.
gh aw trial --clone-repo— "Alternative to --logical-repo" Is MisleadingCommands Affected:
trialPriority: Medium
Type: Inaccurate flag description
Current Output (from running
./gh-aw trial --help, Flags section):Issue: The description calls
--clone-repoan "alternative to--logical-repo", but the Repository modes section in the same help text makes clear they do fundamentally different things:--logical-repo REPO— changes thegithub.repositorycontext (simulates execution as if installed in REPO)--clone-repo REPO— copies REPO's file contents into the trial repository before executionThese are not mutually exclusive alternatives; they address different needs. A user might legitimately use both. Describing one as an "alternative" to the other will cause confusion.
Suggested Fix: Update the flag description to accurately describe what
--clone-repodoes without framing it as an alternative:3.
gh aw mcp add --transport— Inconsistent Capitalization of Transport Type ValuesCommands Affected:
mcp add,mcp inspectPriority: Low
Type: Capitalization inconsistency
Current Output (from running
./gh-aw mcp add --help):Current Output (from running
./gh-aw mcp inspect --help):Issue:
mcp addlists transport types as all-lowercasestdio, http, docker, whilemcp inspectusesDockerandHTTPwith standard capitalization. The values listed inmcp addare likely intended as the literal flag values (where case matters), but the inconsistency across the two commands creates visual confusion.Suggested Fix: Use consistent casing. Since these are literal flag values the user must type, lowercase is appropriate for the
mcp addflag description. Updatemcp inspectprose to use lowercase consistently:4.
gh aw logs --safe-output— Examples Omit Valid Safe-Output TypesCommands Affected:
logsPriority: Low
Type: Incomplete documentation
Current Output (from running
./gh-aw logs --help):Issue: The examples and flag description only mention three safe-output types. Inspecting
pkg/workflow/js/safe_outputs_tools.jsonshows thatnoopandreport-incompleteare also valid tool names produced by workflows. A user trying to filter fornoopcompletions orreport-incompletefailures would not discover these types from the help text.Suggested Fix: Expand the example list to include the most commonly used types: