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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0
• Medium: 2 (Confusing/misleading to users)
• Low: 2 (Minor inconsistencies)

Issue Categories

1. Hidden flag documented in description (1 command) — add
2. Flag semantic conflict across commands (1 command) — trial
3. Usage line incomplete (1 command) — audit
4. Trailing whitespace in source (1 command) — mcp inspect

Inspection Details

• Total Commands Inspected: 24 (--help run on every command and subcommand)
• Commands with Issues: 4
• Date: 2026-03-18
• Method: Executed all CLI commands with --help flags, cross-referenced with docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency (-h, -v, -r, -e, -j, -o, -d, -f, -w, -F)
• Global flag availability on all commands
• Example formatting and style across commands
• Documentation coverage (all commands present in cli.md)
• Short description clarity and brevity
• Enable/disable symmetry
• compile / validate / fix / upgrade flag consistency

⚠️ Issues found:

• Hidden --pr flag documented in add long description but absent from flags list
• trial --repo has different semantics than --repo in every other command
• audit Usage line says (run-id) despite command accepting URLs
• Trailing whitespace in mcp inspect long description source

Detailed Findings

1. add — Hidden --pr alias referenced in Long description

Command Affected: gh aw add
Priority: Medium
Type: Confusing documentation (hidden flag referenced in visible text)

Current output (from ./gh-aw add --help):

The --create-pull-request flag (or --pr) creates a pull request with the workflow changes.
...
Flags:
      --create-pull-request        Create a pull request with the workflow changes
```

**Issue**: The long description explicitly says `(or --pr)`, but `--pr` is registered as a hidden flag (`MarkHidden` in `pkg/cli/add_command.go` line 137) and therefore does not appear in the flags list. Users who read the description and look for `--pr` in the flags will be confused when they don't find it.

**Suggested Fix**: Either:
- Remove the `(or --pr)` reference from the Long description (since the flag is intentionally hidden), **or**
- Unhide `--pr` so it appears in the flags list alongside `--create-pull-request`

---

#### 2. `trial` — `--repo` flag has different semantics from all other commands

**Command Affected**: `gh aw trial`
**Priority**: Medium
**Type**: Semantic inconsistency across commands

**Current 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)
```

**Contrast with every other command** (e.g., `gh aw audit --help`, `gh aw logs --help`, `gh aw status --help`):
```
-r, --repo string   Target repository ([HOST/]owner/repo format). Defaults to current repository
```

**Issue**: In all other commands, `--repo` means "the remote repository to read from or operate on." In `trial`, `--repo` is an alias for `--host-repo` meaning "the repository where workflows are installed and run." The help text acknowledges this conflict with the note `(note: different semantics from --repo in other commands)`, but the inconsistency itself remains and can cause user errors — e.g., a user familiar with `gh aw logs --repo owner/repo` may expect `gh aw trial --repo owner/repo` to have the same read-target semantics.

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

**Suggested Fix**: Consider renaming `--repo` in `trial` to only `--host-repo` (deprecate/remove the `--repo` alias), or add a prominent warning when `--repo` is used in `trial` mode to help users catch this distinction.

---

#### 3. `audit` — Usage line shows `(run-id)` but command also accepts URLs

**Command Affected**: `gh aw audit`
**Priority**: Low
**Type**: Misleading Usage synopsis

**Current output** (from `./gh-aw audit --help`):
```
Usage:
  gh aw audit (run-id) [flags]

Issue: The long description lists 6 different input formats including:

• Numeric run ID: 1234567890
• Workflow run URL: https://github.com/owner/repo/actions/runs/...
• Job URL: https://github.com/owner/repo/actions/runs/.../job/...
• Step URL with #step:7:1
• Short run URL: https://github.com/owner/repo/runs/...
• GitHub Enterprise URLs

The Usage synopsis (run-id) only implies a numeric ID, which understates the command's capabilities. Source: pkg/cli/audit.go line 28 (Use: "audit (run-id)").

Suggested Fix: Update the Usage field to "audit (run-id|url)" or "audit (run-id-or-url)" to match the actual accepted input forms.

---

4. mcp inspect — Trailing whitespace in long description source

Command Affected: gh aw mcp inspect
Priority: Low
Type: Cosmetic / minor whitespace

Source location: pkg/cli/mcp_inspect.go line 204.

Issue: The line "- Validate required secrets are available " has two trailing spaces before the closing quote. While this doesn't affect functionality, it represents unclean source code and can cause issues with diff tools or linters that enforce no trailing whitespace.

Suggested Fix: Remove the trailing spaces from that line.

Generated by CLI Consistency Checker · ◷

• expires on Mar 20, 2026, 1:47 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! 🍪

Note

🔒 Integrity filtering filtered 4 items

Integrity filtering activated and filtered the following items during workflow execution.
This happens when a tool call accesses a resource that does not meet the required integrity or secrecy level of the workflow.

• issue:🔍 Multi-Device Docs Testing Report - 2026-03-20 #21896 (issue_read: Resource 'issue:🔍 Multi-Device Docs Testing Report - 2026-03-20 #21896' has lower integrity than agent requires. Agent would need to drop integrity tags [unapproved:all approved:all] to trust this resource.)
• issue:[cli-consistency] CLI Consistency Issues - 2026-03-18 #21599 (issue_read: Resource 'issue:[cli-consistency] CLI Consistency Issues - 2026-03-18 #21599' has lower integrity than agent requires. Agent would need to drop integrity tags [unapproved:all approved:all] to trust this resource.)
• issue:🔍 Multi-Device Docs Testing Report - 2026-03-19 #21714 (issue_read: Resource 'issue:🔍 Multi-Device Docs Testing Report - 2026-03-19 #21714' has lower integrity than agent requires. Agent would need to drop integrity tags [unapproved:all approved:all] to trust this resource.)
• issue:[refactor] Semantic Function Clustering Analysis: Persistent Outliers and New Findings #21830 (issue_read: Resource 'issue:[refactor] Semantic Function Clustering Analysis: Persistent Outliers and New Findings #21830' has lower integrity than agent requires. Agent would need to drop integrity tags [unapproved:all approved:all] to trust this resource.)

🍪 Om nom nom by Issue Monster · ◷