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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0
• Medium: 1 (Confusing/misleading output)
• Low: 4 (Minor inconsistencies)

Inspection Details

• Total Commands Inspected: 31 (all top-level and subcommands)
• Commands with Issues: 4
• Date: 2026-03-12
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Command descriptions and overall documentation quality
• Flag name conventions (-v, -e, -r, -o, -j, etc.)
• Example accuracy and formatting
• Error message consistency
• Cross-command terminology ("workflow-id", "workflow-id-or-file")

⚠️ Issues found:

• trial command: duplicate default value in help output
• add command: mentions hidden --pr alias in help prose
• mcp-server command: truncated example comment
• completion command: inconsistent "powershell" capitalization

Detailed Findings

1. Duplicate Default Value in trial --timeout Flag

Command Affected: gh aw trial
Priority: Medium
Type: Formatting bug (duplicate text in help output)

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

--timeout int   Execution timeout in minutes (default: 30) (default 30)

Issue: The flag description string already contains (default: 30) in the description text, and Cobra's flag rendering also appends (default 30) automatically for non-zero default values, resulting in the default appearing twice.

Suggested Fix: Remove (default: 30) from the flag description string in pkg/cli/trial_command.go line 189 and let Cobra append it automatically:

// Before:
cmd.Flags().Int("timeout", 30, "Execution timeout in minutes (default: 30)")
// After:
cmd.Flags().Int("timeout", 30, "Execution timeout in minutes")
```

---

#### 2. Hidden `--pr` Alias Mentioned in `add` Help Prose

**Command Affected**: `gh aw add`
**Priority**: Low
**Type**: Documentation inconsistency

**Current Output** (from running `./gh-aw add --help`):
```
The --create-pull-request flag (or --pr) creates a pull request with the workflow changes.
```

But in the flags table, only `--create-pull-request` is shown — `--pr` is intentionally hidden via `cmd.Flags().MarkHidden("pr")`. Users reading the help text see a reference to `--pr` but cannot find it in the flags list.

**Suggested Fix**: Either remove `(or --pr)` from the description prose, or document that it is an undocumented shorthand to avoid confusion.

---

#### 3. Truncated Example Comment in `mcp-server`

**Command Affected**: `gh aw mcp-server`
**Priority**: Low
**Type**: Incomplete comment / poor UX

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

**Issue**: The comment "and actor" is grammatically incomplete. It appears to be a truncated version of "and actor validation" or "with actor configured for access control".

**Suggested Fix**: Update `pkg/cli/mcp_server_command.go` line 62 to something like:
```
DEBUG=mcp:* GITHUB_ACTOR=octocat gh aw mcp-server    # Run with verbose logging and actor validation
```

---

#### 4. Inconsistent "powershell" Capitalization in `completion` Command

**Command Affected**: `gh aw completion`
**Priority**: Low
**Type**: Capitalization inconsistency

**Current Output** (from running `./gh-aw completion --help`):
```
Supported shells: bash, zsh, fish, powershell
```

But in the same command's examples and in the `completion install` / `completion uninstall` help:
```
  # Generate completion script for PowerShell
  gh aw completion powershell | Out-String | Invoke-Expression
```
and:
```
- PowerShell: Provides instructions to add to PowerShell profile

The shell name is "powershell" (lowercase) in the supported-shells list but "PowerShell" (capitalized) in all example comments and completion install/uninstall descriptions.

Suggested Fix: Standardize to "PowerShell" in pkg/cli/completion_command.go line 27:

// Before:
Supported shells: bash, zsh, fish, powershell
// After:
Supported shells: bash, zsh, fish, PowerShell
```

---

#### 5. `trial --repo` Has Different Semantics Than All Other Commands

**Command Affected**: `gh aw trial`
**Priority**: Low
**Type**: Semantic inconsistency / potential user confusion

**Current Output** (from running `./gh-aw trial --help`):
```
--repo string   Alias for --host-repo
```

In every other command (`compile`, `run`, `disable`, `enable`, `logs`, `status`, `audit`, `health`, etc.), `--repo` means **"target/source repository"**:
```
-r, --repo string   Target repository ([HOST/]owner/repo format). Defaults to current repository

In trial, --repo is an alias for --host-repo (the temporary execution host repository), while --logical-repo / -s is the equivalent of the "target repository" used in other commands. Users familiar with other gh aw commands who instinctively set --repo to specify the target workflow repo will accidentally set the host repo instead.

Suggested Fix: Add a note in the --repo flag description and/or the command's Long description explicitly warning that --repo here means --host-repo, not the simulation target:

cmd.Flags().String("repo", "", "Alias for --host-repo (NOTE: unlike other commands, this is the execution host, not the target repo)")

Generated by CLI Consistency Checker · ◷

• expires on Mar 14, 2026, 1:38 PM UTC