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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0 (No functionality-breaking issues)
• Medium: 3 (Misleading or incorrect content)
• Low: 5 (Minor inconsistencies)

Inspection Details

• Total Commands Inspected: 30 (including all subcommands)
• Commands with Issues: 7
• Date: 2026-03-19
• Method: Executed all CLI commands with --help flags and compared with documentation at docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency (-e, -r, -j, -o, -d, -v, -h all consistent)
• Workflow-id description wording (consistent across all applicable commands)
• --stop-after flag description (consistent across add, update, add-wizard)
• --create-pull-request flag (consistent across all commands that support it)
• --repeat flag description and semantics (add, run, trial all consistent)
• --json/-j flag description (consistent across all applicable commands)
• --repo/-r flag description (consistent across all applicable commands except trial - see Finding Add workflow: githubnext/agentics/weekly-research #4)
• --engine/-e flag short name (consistent across all applicable commands)
• Examples in command help text are accurate and follow consistent formatting

⚠️ Issues found:

• Documentation typo in init section
• mcp add vs mcp list-tools inconsistent argument ordering
• Capitalization error in init help text
• trial --repo semantic inconsistency vs all other commands
• mcp-server --cmd ambiguous description
• upgrade --no-fix potentially confusing flag name
• secrets bootstrap unusually long short description
• logs options list incomplete in documentation

Detailed Findings

1. Documentation typo: "logs .gitignore"

Commands Affected: init (documentation only)
Priority: Medium
Type: Typo / Incorrect wording

Location: docs/src/content/docs/setup/cli.md, line 129

Current text:

Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher agent file (`.github/agents/agentic-workflows.agent.md`), and logs `.gitignore`.
```

**Issue**: "logs `.gitignore`" is grammatically incorrect and doesn't describe what the command actually does. The `init` CLI help text mentions configuring `.gitattributes` and creating agent files but makes no mention of `.gitignore` at all.

**Suggested Fix**: Change to "updates `.gitignore`" or remove the `.gitignore` reference if the command no longer modifies it.

---

#### 2. `mcp add` vs `mcp list-tools` inconsistent argument ordering

**Commands Affected**: `mcp add`, `mcp list-tools`
**Priority**: Medium
**Type**: Argument ordering inconsistency

**Current CLI output** (from `./gh-aw mcp add --help`):
```
Usage:
  gh aw mcp add [workflow] [server] [flags]

Examples:
  gh aw mcp add weekly-research makenotion/notion-mcp-server
```

**Current CLI output** (from `./gh-aw mcp list-tools --help`):
```
Usage:
  gh aw mcp list-tools (server) [workflow] [flags]

Examples:
  gh aw mcp list-tools github weekly-research
```

**Issue**: The two `mcp` subcommands reverse the order of `workflow` and `server` positional arguments. In `mcp add`, workflow comes first then server; in `mcp list-tools`, server comes first then workflow. Users switching between these commands may easily confuse the argument order.

**Suggested Fix**: Standardize the argument order across `mcp` subcommands. Since `mcp add` already uses `[workflow] [server]` and `mcp inspect` uses workflow as the primary arg (with server as a `--server` flag), making `mcp list-tools` use `[workflow] [server]` order would be consistent.

---

#### 3. Lowercase "github" in `init` help text

**Commands Affected**: `init`
**Priority**: Medium
**Type**: Capitalization error

**Current CLI output** (from `./gh-aw init --help`):
```
To create, update or debug automated agentic actions using github, playwright, and other tools, load the .github/agents/agentic-workflows.agent.md (applies to .github/workflows/*.md)
```

**Issue**: "github" should be capitalized as "GitHub" — it refers to the GitHub product/platform. All other occurrences in the help text use the correct capitalization.

**Suggested Fix**: Change "using github, playwright" to "using GitHub, Playwright" (both are product names that should be capitalized).

---

#### 4. `trial --repo` has different semantics from all other commands

**Commands Affected**: `trial`
**Priority**: Low
**Type**: Semantic inconsistency

**Current CLI output** (from `./gh-aw trial --help`):
```
  --repo string                     Alias for --host-repo: the repository where workflows are installed and run (note: different semantics from --repo in other commands)
```

**Issue**: In every other command (`audit`, `disable`, `enable`, `logs`, `run`, `status`, `health`, `checks`), `--repo` means "the target repository to operate against". In `trial`, it means "the host repository for trial execution" which has fundamentally different semantics. While the help text does include a warning note, this can still cause confusion.

**Suggested Fix**: Consider deprecating `--repo` in `trial` in favor of always requiring `--host-repo`, or making the warning more prominent. Alternatively, document this exception more clearly in the docs.

---

#### 5. `mcp-server --cmd` description is ambiguous

**Commands Affected**: `mcp-server`
**Priority**: Low
**Type**: Ambiguous description

**Current CLI output** (from `./gh-aw mcp-server --help`):
```
  --cmd string       Path to gh aw command to use (defaults to 'gh aw')
```

**Example in help text**:
```
  gh aw mcp-server --cmd ./gh-aw       # Use custom gh-aw binary path
```

**Issue**: The flag description says "Path to gh aw command" but the default value `'gh aw'` is a shell command (not a file path). Users may be confused whether to provide a file path (like `./gh-aw`) or a shell command (like `gh aw`).

**Suggested Fix**: Change to "Command or path for gh-aw binary (defaults to 'gh aw')" to clarify that both a shell command string and a file path are accepted.

---

#### 6. `upgrade --no-fix` flag name is potentially misleading

**Commands Affected**: `upgrade`
**Priority**: Low
**Type**: Misleading flag name

**Current CLI output** (from `./gh-aw upgrade --help`):
```
      --no-fix                Skip applying codemods, action updates, and compiling workflows (only update agent files)
```

**Issue**: The `--no-fix` flag actually skips three things: codemods, action updates, AND compilation. But there are also separate `--no-actions` and `--no-compile` flags. A user who wants to skip codemods but still run action updates and compilation may not realize `--no-fix` skips all three steps. The description does clarify this, but the flag name implies only skipping "fix" (codemods).

**Suggested Fix**: Consider renaming the flag to `--agent-files-only` or `--no-upgrade` and updating the description, or keeping `--no-fix` but making the description even clearer: "Skip codemods, action updates, AND compilation (equivalent to: update agent files only)".

---

#### 7. `secrets bootstrap` has an unusually long short description

**Commands Affected**: `secrets bootstrap`
**Priority**: Low
**Type**: Inconsistent description length/style

**Current CLI output** (from `./gh-aw secrets bootstrap --help`):
```
Analyzes all workflows in the repository to determine which secrets
are required, checks which ones are already configured, and interactively
prompts for any missing required secrets.
```

**Issue**: Most commands use a concise single-line short description (e.g., `add`: "Add one or more agentic workflows from repositories to .github/workflows."). The `secrets bootstrap` short description spans 3 lines, which looks inconsistent in the parent `secrets --help` listing.

**Suggested Fix**: Shorten to something like: "Analyze workflows and set up required secrets" (matching the Listed subcommand description in `secrets --help`).

---

#### 8. `logs` options list in documentation is incomplete

**Commands Affected**: `logs` (documentation only)
**Priority**: Low
**Type**: Incomplete documentation

**Location**: `docs/src/content/docs/setup/cli.md`

**Current documentation**:
```
**Options:** `-c`, `--count`, `-e`, `--engine`, `--start-date`, `--end-date`, `--ref`, `--parse`, `--json`, `--repo`

Flags present in CLI but missing from docs (from ./gh-aw logs --help):

• --after-run-id — Filter runs with database ID after a value
• --before-run-id — Filter runs with database ID before a value
• --firewall / --no-firewall — Filter by firewall status
• --no-staged — Filter out staged workflow runs
• --safe-output — Filter by safe output type (e.g., create-issue, missing-tool)
• --tool-graph — Generate Mermaid tool sequence graph
• --timeout — Download timeout in seconds
• --summary-file — Custom summary JSON file path

Suggested Fix: Update the docs options list to include at least the most useful of these flags, or expand the docs section to better reflect the command's filtering capabilities.

Generated by CLI Consistency Checker · ◷

• expires on Mar 21, 2026, 1:41 PM UTC