Detailed Findings
1. mcp add Misleading Description: "tool" vs "server"
Command Affected: gh aw mcp add
Priority: Medium
Type: Misleading description
Current Output (from ./gh-aw mcp add --help):
Add an MCP tool to an agentic workflow by searching the MCP registry.
This command searches the MCP registry for the specified server, adds it to the workflow's tools section,
and automatically compiles the workflow. If the tool already exists, the command will fail.
Issue: The first line says "Add an MCP tool" but the very next sentence says it "searches the MCP registry for the specified server" and "adds it to the workflow's tools section". The command actually adds an MCP server configuration, not an individual tool. This creates confusion between the command description and its actual operation.
Suggested Fix: Change the first line to:
Add an MCP server to an agentic workflow by searching the MCP registry.
2. logs --after Flag Name Confusing for Cache Cleanup
Command Affected: gh aw logs
Priority: Medium
Type: Confusing/misleading flag name
Current Output (from ./gh-aw logs --help):
--after string Remove locally cached run folders created before this date (cache cleanup).
Use deltas like -1w or -1mo, or an absolute date YYYY-MM-DD.
For example, --after -1w removes folders older than 1 week.
--after-run-id int Filter runs with database ID after this value (exclusive)
Issue: The --after flag does cache cleanup (removes local folders created BEFORE a given date), but its name implies it's a date filter for runs created AFTER a date — especially confusing alongside --start-date (which filters runs created after a date) and --after-run-id (which filters runs by ID after a value). A user would likely expect --after to be an alias for --start-date, not a cache cleanup mechanism.
Suggested Fix: Consider renaming the flag to --purge-before or --cleanup-older-than, or at minimum improve the description to make the cache cleanup purpose more prominent:
--cleanup string Remove locally cached run folders older than this date/delta (cache cleanup). Use -1w, -30d, -1mo, or YYYY-MM-DD
3. mcp add --transport Inconsistent Value Casing
Command Affected: gh aw mcp add
Priority: Low
Type: Minor inconsistency
Current Output (from ./gh-aw mcp add --help):
--transport string Preferred transport type (stdio, HTTP, Docker)
Issue: The accepted values use mixed casing: stdio is lowercase while HTTP and Docker are title-cased. This is inconsistent and may confuse users about the actual accepted values.
Suggested Fix: Use consistent lowercase: (stdio, http, docker) — or use the actual enum values accepted by the flag.
4. trial Uses Non-Standard Terminology "GitHub space"
Command Affected: gh aw trial
Priority: Low
Type: Non-standard terminology
Current Output (from ./gh-aw trial --help):
This command creates a temporary private repository in your GitHub space, installs the specified
workflow(s) from their source repositories, and runs them in "trial mode"...
Issue: "GitHub space" is not standard GitHub terminology. The correct term is "GitHub account" or simply "your account".
Suggested Fix: Change to:
This command creates a temporary private repository in your GitHub account, installs the specified...
5. add Short Description Omits Local File Support
Command Affected: gh aw add
Priority: Low
Type: Incomplete description
Current Output (from ./gh-aw add --help):
Add one or more agentic workflows from repositories to .github/workflows.
Issue: The short description says "from repositories" but the command also supports adding local files (./my-workflow.md, ./*.md). A user looking only at the short description (e.g., in gh aw --help listing) would not know local workflows are supported. The main --help listing also reads: add Add agentic workflows from repositories to .github/workflows.
Suggested Fix: Change to:
Add one or more agentic workflows from repositories or local files to .github/workflows.
Summary
Automated CLI consistency inspection found 5 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.
Breakdown by Severity
Inspection Details
--helpflags run for main + all subcommands)--helpflags and analyzed actual output vs docsFindings Summary
✅ No issues found in these areas:
-r/--repo,-e/--engine,-j/--json,-v/--verbose,-o/--output)-h/--helpon every command)--banner,--verbose)mcp adddescription says "tool" but adds a "server"logs --afterflag name is confusing vs its purpose (cache cleanup, not run filtering)mcp add --transportvalue casing inconsistencytrialuses non-standard terminology "GitHub space"addshort description omits local file supportDetailed Findings
1.
mcp addMisleading Description: "tool" vs "server"Command Affected:
gh aw mcp addPriority: Medium
Type: Misleading description
Current Output (from
./gh-aw mcp add --help):Issue: The first line says "Add an MCP tool" but the very next sentence says it "searches the MCP registry for the specified server" and "adds it to the workflow's tools section". The command actually adds an MCP server configuration, not an individual tool. This creates confusion between the command description and its actual operation.
Suggested Fix: Change the first line to:
2.
logs --afterFlag Name Confusing for Cache CleanupCommand Affected:
gh aw logsPriority: Medium
Type: Confusing/misleading flag name
Current Output (from
./gh-aw logs --help):Issue: The
--afterflag does cache cleanup (removes local folders created BEFORE a given date), but its name implies it's a date filter for runs created AFTER a date — especially confusing alongside--start-date(which filters runs created after a date) and--after-run-id(which filters runs by ID after a value). A user would likely expect--afterto be an alias for--start-date, not a cache cleanup mechanism.Suggested Fix: Consider renaming the flag to
--purge-beforeor--cleanup-older-than, or at minimum improve the description to make the cache cleanup purpose more prominent:3.
mcp add --transportInconsistent Value CasingCommand Affected:
gh aw mcp addPriority: Low
Type: Minor inconsistency
Current Output (from
./gh-aw mcp add --help):Issue: The accepted values use mixed casing:
stdiois lowercase whileHTTPandDockerare title-cased. This is inconsistent and may confuse users about the actual accepted values.Suggested Fix: Use consistent lowercase:
(stdio, http, docker)— or use the actual enum values accepted by the flag.4.
trialUses Non-Standard Terminology "GitHub space"Command Affected:
gh aw trialPriority: Low
Type: Non-standard terminology
Current Output (from
./gh-aw trial --help):Issue: "GitHub space" is not standard GitHub terminology. The correct term is "GitHub account" or simply "your account".
Suggested Fix: Change to:
5.
addShort Description Omits Local File SupportCommand Affected:
gh aw addPriority: Low
Type: Incomplete description
Current Output (from
./gh-aw add --help):Issue: The short description says "from repositories" but the command also supports adding local files (
./my-workflow.md,./*.md). A user looking only at the short description (e.g., ingh aw --helplisting) would not know local workflows are supported. The main--helplisting also reads:add Add agentic workflows from repositories to .github/workflows.Suggested Fix: Change to: