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

[github-actions]

Summary

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

Breakdown by Severity

• High: 1 (Documented command doesn't exist)
• Medium: 4 (Misleading/confusing text)
• Low: 4 (Minor style/alignment inconsistencies)

Issue Categories

1. Missing command (1 command) — audit report documented but not implemented
2. Description mismatches (2 commands) — secrets, mcp-server
3. Incorrect terminology (1 command) — init
4. Style/formatting inconsistencies (4 commands) — logs, audit diff, trial, logs

Inspection Details

• Total Commands Inspected: 32 (all top-level and subcommands, including add, add-wizard, audit, audit diff, checks, compile, completion, disable, domains, enable, fix, hash-frontmatter, health, init, list, logs, mcp, mcp add, mcp inspect, mcp list, mcp list-tools, mcp-server, new, pr, pr transfer, project, project new, remove, run, secrets, secrets bootstrap, secrets set, status, trial, update, upgrade, validate, version)
• Commands with Issues: 8
• Date: 2026-04-06
• Method: Executed all CLI commands with --help flags and analyzed actual output vs. documentation

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency (-h/--help, -v/--verbose, -r/--repo, -j/--json, -e/--engine, -o/--output)
• Example format and comment style (within each command)
• Workflow ID format documentation (consistent across all commands)
• Subcommand structure and nesting
• Global flags consistency

⚠️ Issues found:

• Documented audit report subcommand is not implemented (CLI falls back to main audit help)
• secrets --help bullet description for bootstrap doesn't match Available Commands listing
• mcp-server --help has incomplete grammar in example comment
• init --help uses "agentic actions" where it should say "agentic workflows"
• Non-standard "write+" notation in mcp-server --help
• Inconsistent option ordering for --format between logs and audit diff
• Example alignment inconsistency in trial --help
• Unusual --last flag description in logs --help

Detailed Findings

1. audit report Subcommand Documented but Not Implemented

Commands Affected: audit
Priority: High
Type: Missing implementation / Documentation ahead of code

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

Available Commands:
  diff Compare behavior across workflow runs
```

Running `./gh-aw audit report --help` silently falls back to the main `audit` help (treats "report" as a run-id argument).

**Documentation** (`docs/src/content/docs/setup/cli.md`):
```
##### `audit report`

Generate a comprehensive cross-run security audit report by aggregating firewall data
across multiple recent runs.

gh aw audit report                                          # Report on recent runs (default: last 20)
gh aw audit report --workflow "agent-task" --last 10        # Report on last 10 runs of a workflow
gh aw audit report --workflow "agent-task" --last 5 --json  # JSON for dashboards
gh aw audit report --format pretty                          # Console-formatted output
gh aw audit report --repo owner/repo --last 10              # Report on a specific repository
```

**Issue**: The docs describe `gh aw audit report` as a full subcommand with `--workflow`, `--last`, `--format`, and `--repo` flags. The command does not exist. The cross-run security report functionality is actually accessible via `gh aw logs --format markdown` / `gh aw logs --format pretty`.

**Suggested Fix**: Either implement `audit report` as a subcommand (forwarding to `logs --format`), or update the documentation to replace `audit report` examples with the correct `logs --format` equivalents.

---

### 2. `secrets bootstrap` Description Mismatch in Parent Help

**Commands Affected**: `secrets`
**Priority**: Medium
**Type**: Description inconsistency

**Current CLI Output** (from `./gh-aw secrets --help`):
```
Available subcommands:
  • set       - Create or update individual secrets
  • bootstrap - Validate and configure all required secrets for workflows

Available Commands:
  bootstrap Analyze workflows and set up required secrets
  set       Create or update a repository secret
```

**Issue**: Two descriptions are shown for `bootstrap` in the same help output and they don't match:
- Bullet list: "Validate and configure all required secrets for workflows"
- `Available Commands` listing: "Analyze workflows and set up required secrets"

The actual `secrets bootstrap --help` says "Analyze all workflows in the repository to determine which secrets are required..." which aligns with the `Available Commands` entry but not the bullet.

**Suggested Fix**: Update the bullet description to match the Available Commands entry: "Analyze workflows and set up required secrets for workflows"

---

### 3. Incomplete Grammar in `mcp-server` Example Comment

**Commands Affected**: `mcp-server`
**Priority**: Medium
**Type**: Typo / Grammar

**Current CLI Output** (from `./gh-aw mcp-server --help`):
```
Examples:
  gh aw mcp-server                                     # Run with stdio transport (default for MCP clients)
  gh aw mcp-server --validate-actor                    # Run with actor validation enforced
  gh aw mcp-server --port 8080                         # Run HTTP server on port 8080 (for web-based clients)
  gh aw mcp-server --cmd ./gh-aw                       # Use custom gh-aw binary path
  GITHUB_ACTOR=octocat gh aw mcp-server                # Set actor via environment variable for access control
  DEBUG=mcp:* GITHUB_ACTOR=octocat gh aw mcp-server    # Run with verbose logging and actor
```

**Issue**: The last example comment "# Run with verbose logging and actor" is grammatically incomplete. "and actor" doesn't form a complete thought.

**Suggested Fix**: Change to "# Run with debug logging and actor set for access control" or "# Enable debug logging with actor for access control"

---

### 4. "Agentic Actions" Should Be "Agentic Workflows" in `init` Help

**Commands Affected**: `init`
**Priority**: Medium
**Type**: Incorrect terminology

**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**: "agentic actions" is confusing because "GitHub Actions" is a distinct product name. The tool manages "agentic workflows", not "agentic actions". This could mislead users into thinking this refers to GitHub Actions itself.

**Suggested Fix**: Change "agentic actions" to "agentic workflows":
```
To create, update or debug automated agentic workflows using GitHub, playwright, and other tools,
load the .github/agents/agentic-workflows.agent.md (applies to .github/workflows/*.md)
```

---

### 5. Non-Standard "write+" Notation in `mcp-server` Help

**Commands Affected**: `mcp-server`
**Priority**: Medium
**Type**: Non-standard terminology

**Current CLI Output** (from `./gh-aw mcp-server --help`):
```
  Tools requiring elevated permissions (logs, audit) are always
  mounted but will return permission denied errors if the actor lacks write+ access.

  Use the --validate-actor flag to enforce actor validation. When enabled, logs and audit
  tools will return permission denied errors if GITHUB_ACTOR is not set. When disabled
  (default), these tools will work without actor validation.
```

**Issue**: "write+" is not standard GitHub terminology. GitHub uses "write or higher" or "write access or above" in its official documentation.

**Suggested Fix**: Replace "write+ access" with "write access or higher" to align with standard GitHub terminology.

---

### 6. Inconsistent `--format` Option Ordering Between `logs` and `audit diff`

**Commands Affected**: `logs`, `audit diff`
**Priority**: Low
**Type**: Style inconsistency

**Current CLI Output**:

From `./gh-aw logs --help`:
```
--format string   Output format for cross-run audit report: markdown, pretty
```

From `./gh-aw audit diff --help`:
```
--format string   Output format: pretty, markdown (default "pretty")
```

**Issue**: The `logs` command lists "markdown, pretty" while `audit diff` lists "pretty, markdown". When the default is `pretty`, it's conventional to list the default first.

**Suggested Fix**: Update `logs --format` flag description to list "pretty, markdown" for consistency with `audit diff`, or add "(default "pretty")" to clarify.

---

### 7. Example Alignment Issue in `trial` Help

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

**Current CLI Output** (from `./gh-aw trial --help`):
```
  gh aw trial githubnext/agentics/my-workflow --repeat 3                # Run 4 times total (1 initial + 3 repeats)
  gh aw trial githubnext/agentics/my-workflow --delete-host-repo-after  # Delete repo after completion
  gh aw trial githubnext/agentics/my-workflow --host-repo my-trial       # Custom host repo
  gh aw trial githubnext/agentics/my-workflow --host-repo . # Use current repo as host
```

**Issue**: The last example `--host-repo . # Use current repo as host` has only a single space before `#`, while all other examples use double space padding for alignment.

**Suggested Fix**: Add a space: `gh aw trial githubnext/agentics/my-workflow --host-repo .  # Use current repo as host`

---

### 8. Unusual `--last` Flag Description in `logs` Help

**Commands Affected**: `logs`
**Priority**: Low
**Type**: Inconsistent flag description style

**Current CLI Output** (from `./gh-aw logs --help`):
```
  --last int   Alias for --count: number of recent runs to analyze when generating a cross-run report

Issue: Describing a flag as "Alias for --count:" followed by a colon and the actual description is an unusual pattern. Most flag descriptions are self-contained. Users might wonder why both --last and --count exist if they're identical.

Suggested Fix: Either document the semantic difference (if any) or simplify to: --last int Number of recent runs to analyze in cross-run reports (alias for --count)

---

9. Inconsistent --format flag description length

Commands Affected: audit diff, logs
Priority: Low
Type: Style inconsistency

audit diff --format: Output format: pretty, markdown (default "pretty")
logs --format: Output format for cross-run audit report: markdown, pretty (generates security audit report instead of default metrics table)

The logs description is significantly more verbose and could confuse users about when --format activates the audit report mode vs. the default metrics table.

Suggested Fix: Keep the descriptions concise and consistent. For logs: Output format for cross-run security report: pretty, markdown (default "pretty"; triggers security audit report mode)

Generated by CLI Consistency Checker · ● 1.1M · ◷

• expires on Apr 8, 2026, 1:46 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot coding agent.

The Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · ● 174K · ◷