-
Notifications
You must be signed in to change notification settings - Fork 278
Description
Summary
Automated CLI consistency inspection found 5 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.
Note: The CLI binary could not be compiled (requires Go 1.25.0 which is not available in the runner), so this inspection was performed by analyzing source code directly. All findings are verified against source files.
Breakdown by Severity
- High: 1 (Example uses wrong flag letter — users copying it will get errors)
- Medium: 1 (Incorrect default URL shown in flag description)
- Low: 3 (Minor inconsistencies)
Inspection Details
- Total Commands Inspected: 22 (including all subcommands)
- Commands with Issues: 5
- Date: 2026-02-19
- Method: Source code analysis of all
*_command.gofiles andcmd/gh-aw/main.go
Findings Summary
✅ No issues found in these areas:
- Short descriptions (no trailing punctuation)
- Argument syntax conventions (
(required)vs[optional]) - Examples existence (all commands with flags have examples)
- Docs URL accuracy (
https://github.github.com/gh-aw/is correct) WorkflowIDExplanationusage is consistent across commands
runcommand example (-fvs-F)mcp addregistry URL in flag description--repoflag description inconsistencynewcommand terminologyproject newexample indentation
Detailed Findings
1. run Command Example Uses Wrong Short Flag Letter
Commands Affected: run
Priority: High
Type: Bug in help text — wrong flag short form
Current Output (from cmd/gh-aw/main.go line 360):
gh aw run daily-perf-improver -f name=value -f env=prod # Pass workflow inputs
Actual flag definition (cmd/gh-aw/main.go line 590):
runCmd.Flags().StringArrayP("raw-field", "F", []string{}, "Add a string parameter in key=value format (can be used multiple times)")
```
**Issue**: The `--raw-field` flag is registered with the short form `-F` (uppercase), but the example in the Long description uses `-f` (lowercase). Since the `new` command already uses `-f` for `--force`, users copying the example will get an error like `unknown shorthand flag: 'f' in -f`.
**Suggested Fix**: Change the example on line 360 to use `-F`:
```
gh aw run daily-perf-improver -F name=value -F env=prod # Pass workflow inputs
```
---
#### 2. `mcp add` `--registry` Flag Description Shows Wrong Default URL
**Commands Affected**: `mcp add`
**Priority**: Medium
**Type**: Inaccurate flag description
**Current Output** (`pkg/cli/mcp_add.go` line 362):
```
--registry MCP registry URL (default: https://api.mcp.github.com/v0)Correct value (from pkg/constants/constants.go line 309):
const DefaultMCPRegistryURL URL = "https://api.mcp.github.com/v0.1"Issue: The --registry flag description says the default is https://api.mcp.github.com/v0 but the actual constant DefaultMCPRegistryURL is https://api.mcp.github.com/v0.1. Ironically, the Long description on the same command (line 335) correctly shows v0.1.
Suggested Fix: Update the flag description on line 362 from v0 to v0.1:
cmd.Flags().StringVar(®istryURL, "registry", "", "MCP registry URL (default: https://api.mcp.github.com/v0.1)")
```
---
#### 3. `--repo` Flag Description Inconsistency Across Commands
**Commands Affected**: `status`, `enable`, `disable`, `run`
**Priority**: Low
**Type**: Inconsistency between standard helper and inline definitions
**Current Output**:
- `flags.go` helper (used by `pr transfer`, `list`, etc.):
```
-r, --repo Target repository ([HOST/]owner/repo format). Defaults to current repository
```
- `status`, `enable`, `disable`, `run` commands (defined inline in `status.go` and `main.go`):
```
-r, --repo Target repository (owner/repo format). Defaults to current repository
```
**Issue**: The `[HOST/]owner/repo` format (which supports GitHub Enterprise Server) is documented in `addRepoFlag()` helper but omitted when the flag is defined inline in `status.go`, `enableCmd`, `disableCmd`, and `runCmd` (4 occurrences). This is inconsistent and misleads GHES users who try to use these commands with GHES.
**Suggested Fix**: Update the 4 inline definitions to use `"[HOST/]owner/repo format"` or refactor them to use `addRepoFlag()`.
---
#### 4. `new` Command Uses Non-Standard Terminology "AI processor settings"
**Commands Affected**: `new`
**Priority**: Low
**Type**: Inconsistent terminology
**Current Output** (`cmd/gh-aw/main.go` line 114):
```
- AI processor settings
```
**Issue**: The `new` command's `Long` description lists content created by the template as including "AI processor settings". The rest of the codebase consistently uses "engine" (not "processor") for the AI component — `--engine` flag, `Short: "Override AI engine"`, docs use "engine". This one-off term is inconsistent.
**Suggested Fix**: Change "AI processor settings" to "AI engine settings":
```
- AI engine settings
```
---
#### 5. `project new` Example Has Inconsistent Indentation
**Commands Affected**: `project new`
**Priority**: Low
**Type**: Visual inconsistency in help text
**Current Output** (`pkg/cli/project_command.go`):
```
Examples:
gh aw project new "My Project" --owner `@me` # Create user project
gh aw project new "Team Board" --owner myorg # Create org project
gh aw project new "Bugs" --owner myorg --link myorg/myrepo # Create and link to repo
gh aw project new "Project Q1" --owner myorg --with-project-setup # With project setupIssue: The last example line uses a tab character for indentation while all others use 2 spaces. When rendered in a terminal, this will cause the last example to be misaligned (tab typically renders as 8 spaces or stops).
Suggested Fix: Replace the tab with 2 spaces on the last example line so all examples are consistently indented:
gh aw project new "Project Q1" --owner myorg --with-project-setup # With project setupGenerated by CLI Consistency Checker
- expires on Feb 21, 2026, 1:39 PM UTC