[cli-consistency] CLI Consistency Issues - 2026-03-04

[github-actions]

Summary

Automated CLI consistency inspection found 6 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.

Breakdown by Severity

• High: 0 (Breaks functionality)
• Medium: 1 (Confusing/misleading)
• Low: 5 (Minor inconsistencies)

Issue Categories

1. Notation inconsistency in example comments (1 command)

   • Examples use hyphens in flag values but underscores in inline comments
   • Affects: logs

2. Hidden flag referenced in visible help body (1 command)

   • Flag is hidden from the flags list but explicitly named in help prose
   • Affects: add

3. Capitalization inconsistency (1 command)

   • "GH-AW" used in flag description, inconsistent with lowercase "gh-aw" convention
   • Affects: init

4. Unclear/incomplete example comment (1 command)

   • Grammatically incomplete comment in examples
   • Affects: mcp-server

5. Non-intuitive short flag assignment (1 command)

   • Short flag -s for --logical-repo is not mnemonic
   • Affects: trial

6. Missing description and examples (1 command)

   • version help is extremely minimal compared to all other commands
   • Affects: version

Inspection Details

• Total Commands Inspected: 23 (all listed commands + subcommands run with --help)
• Commands with Issues: 6
• Date: 2026-03-04
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming and consistency across commands (-e, -r, -o, -j, etc.)
• Example accuracy and completeness (most commands)
• Subcommand grouping and organization
• Grammar and spelling in most command descriptions
• add, audit, compile, disable, enable, init, logs, mcp, new, pr, remove, run, status, trial, update, mcp add, mcp inspect, mcp list, mcp list-tools, pr transfer

⚠️ Issues found:

• Hyphen/underscore notation inconsistency in logs examples
• Hidden --pr flag referenced in visible add help text
• GH-AW capitalization in init flag description
• Unclear comment in mcp-server examples
• Non-intuitive -s short flag in trial
• Minimal help for version

Detailed Findings

1. logs — Notation inconsistency: hyphens vs. underscores in example comments

Command Affected: logs
Priority: Medium
Type: Inconsistency

Current Output (from ./gh-aw logs --help):

  gh aw logs --safe-output missing-tool     # Filter logs with missing_tool messages
  gh aw logs --safe-output missing-data     # Filter logs with missing_data messages
  gh aw logs --safe-output create-issue     # Filter logs with create_issue messages
```

**Issue**: The actual flag values use hyphens (`missing-tool`, `missing-data`, `create-issue`) but the inline comments reference them with underscores (`missing_tool`, `missing_data`, `create_issue`). Users may be confused about whether to use hyphens or underscores when invoking the flag.

**Suggested Fix**: Update the inline comments to use the same hyphenated notation as the flag values:
```
  gh aw logs --safe-output missing-tool     # Filter logs with missing-tool messages
  gh aw logs --safe-output missing-data     # Filter logs with missing-data messages
  gh aw logs --safe-output create-issue     # Filter logs with create-issue messages
```
**Source**: `pkg/cli/logs_command.go` lines 71-73

---

#### 2. `add` — Hidden `--pr` flag mentioned in visible help body

**Command Affected**: `add`
**Priority**: Low
**Type**: Inconsistency between visible help text and flags list

**Current Output** (from `./gh-aw add --help`):
```
The --create-pull-request flag (or --pr) creates a pull request with the workflow changes.
```
(But `--pr` does not appear in the `Flags:` section because it is marked as hidden)

**Issue**: The help body explicitly mentions `--pr` as a usable alias, but the flags list hides it. Users who notice the mention in the body text but cannot find it in the flags list may be confused. Either the reference should be removed from the body text or the flag should be surfaced.

**Suggested Fix**: Either remove the `(or --pr)` parenthetical from the prose, or un-hide the `--pr` flag in the flags list to be consistent.

**Source**: `pkg/cli/add_command.go` line 76 (prose) and line 136 (`MarkHidden`)

---

#### 3. `init` — Inconsistent capitalization "GH-AW" in flag description

**Command Affected**: `init`
**Priority**: Low
**Type**: Capitalization inconsistency

**Current Output** (from `./gh-aw init --help`):
```
      --no-mcp                    Skip configuring GH-AW MCP server integration for GitHub Copilot Agent
```

**Issue**: The `--no-mcp` flag description uses "GH-AW" (uppercase with hyphen). Every other place in the CLI output uses lowercase "gh-aw", including adjacent text in the same `init --help` output:
```
- Creates .github/workflows/copilot-setup-steps.yml with gh-aw installation steps
- Creates .vscode/mcp.json with gh-aw MCP server configuration
```

**Suggested Fix**: Change "GH-AW" to "gh-aw" in the flag description:
```
      --no-mcp                    Skip configuring gh-aw MCP server integration for GitHub Copilot Agent
```
**Source**: `pkg/cli/init_command.go` line 124

---

#### 4. `mcp-server` — Unclear example comment

**Command Affected**: `mcp-server`
**Priority**: Low
**Type**: Unclear/incomplete comment

**Current Output** (from `./gh-aw mcp-server --help`):
```
  DEBUG=mcp:* GITHUB_ACTOR=octocat gh aw mcp-server    # Run with verbose logging and actor
```

**Issue**: The comment "Run with verbose logging and actor" is grammatically incomplete — "and actor" is a dangling phrase. It's unclear what "actor" means here without context.

**Suggested Fix**: Use a more descriptive and complete comment:
```
  DEBUG=mcp:* GITHUB_ACTOR=octocat gh aw mcp-server    # Run with debug logging and GITHUB_ACTOR set
```
**Source**: `pkg/cli/mcp_server_command.go` line 62

---

#### 5. `trial` — Non-intuitive short flag `-s` for `--logical-repo`

**Command Affected**: `trial`
**Priority**: Low
**Type**: Non-intuitive flag naming

**Current Output** (from `./gh-aw trial --help`):
```
  -s, --logical-repo string             The repo we're simulating the execution for...
```

**Issue**: The short flag `-s` does not mnemically relate to `--logical-repo`. Users would naturally expect `-l` (for "logical") or similar. The `-s` may stand for "simulate/simulation" but this relationship is not obvious, especially since the full flag name contains neither "s" nor "simulate".

**Suggested Fix**: Consider changing the short flag to `-l` if it's not already used, or document the rationale in the help text. (Note: check for conflicts with existing short flags before changing.)

**Source**: `pkg/cli/trial_command.go` line 180

---

#### 6. `version` — Minimal help with no description or examples

**Command Affected**: `version`
**Priority**: Low
**Type**: Missing documentation

**Current Output** (from `./gh-aw version --help`):
```
Show gh aw extension version information

Usage:
  gh aw version [flags]

Flags:
  -h, --help   help for version

Global Flags:
      --banner    Display ASCII logo banner with purple GitHub color theme
  -v, --verbose   Enable verbose output showing detailed information
```

**Issue**: The `version` command has only a one-line description and no examples, unlike all other commands which include detailed descriptions and multiple examples. Users don't know what format the output takes or how to use it in scripts.

**Suggested Fix**: Add examples showing typical usage and what the output format looks like:
```
Examples:
  gh aw version                    # Show current version
  gh aw version --json             # Output version in JSON format (if supported)

Source: pkg/cli/version_command.go

Generated by CLI Consistency Checker · ◷

• expires on Mar 6, 2026, 1:34 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-03-06T13:34:12.745Z.

Closed by Workflow