Skip to content

[cli-consistency] CLI Consistency Issues - 2026-02-19 #16827

@github-actions

Description

@github-actions

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.go files and cmd/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)
  • WorkflowIDExplanation usage is consistent across commands

⚠️ Issues found in:

  • run command example (-f vs -F)
  • mcp add registry URL in flag description
  • --repo flag description inconsistency
  • new command terminology
  • project new example 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(&registryURL, "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 setup

Issue: 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 setup

Generated by CLI Consistency Checker

  • expires on Feb 21, 2026, 1:39 PM UTC

Metadata

Metadata

Labels

automationclicookieIssue Monster Loves Cookies!documentationImprovements or additions to documentation

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions