[cli-consistency] CLI Consistency Issues - 2026-02-25

[github-actions]

Summary

Automated CLI consistency inspection (run 22399090301) found 4 inconsistencies in command help text that should be addressed for better user experience.

Breakdown by Severity

• High: 1 (Broken example referencing non-existent flag)
• Medium: 1 (Inconsistent verbose flag definition)
• Low: 2 (Minor inconsistencies)

Inspection Details

• Total Commands Inspected: 35 (--help executed for all commands and subcommands)
• Commands with Issues: 3
• Date: 2026-02-25
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency across commands
• Example correctness (except trial)
• Global flags consistency (except pr transfer)
• Documentation cross-reference with docs/src/content/docs/setup/cli.md
• MCP registry URL consistency (v0.1 is used consistently in both description and flag default)

⚠️ Issues found:

• trial help text — broken example references non-existent --quiet flag
• pr transfer — defines -v/--verbose as a local flag instead of inheriting from global flags
• All subcommands — Usage lines show gh (cmd) instead of gh aw (cmd)
• secrets bootstrap — missing Examples: section

Detailed Findings

1. trial Example References Non-Existent --quiet Flag

Command Affected: gh aw trial
Priority: High
Type: Broken example / missing flag

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

Repeat and cleanup examples:
  gh aw trial githubnext/agentics/my-workflow --repeat 3                # Run 3 times total
  gh aw trial githubnext/agentics/my-workflow --delete-host-repo-after  # Delete repo after completion
  gh aw trial githubnext/agentics/my-workflow --quiet --host-repo my-trial # Custom host repo
  gh aw trial githubnext/agentics/my-workflow --dry-run                 # Show what would be done without changes
```

**Issue**: The example `gh aw trial ... --quiet --host-repo my-trial` uses `--quiet`, which is **not a registered CLI flag**. Running this example would fail with `unknown flag: --quiet`. In the source code (`pkg/cli/trial_command.go`), the `Quiet bool` option in `TrialOptions` is set to the value of `--yes`/`-y`, but no `--quiet` flag is registered via `cmd.Flags()`. The comment `# Custom host repo` doesn't match the `--quiet` flag either — the example appears to be testing `--host-repo` but has a leftover `--quiet` that was never implemented or was removed.

**Suggested Fix**: Remove `--quiet` from the example, or register it as a proper flag. The example should be:
```
gh aw trial githubnext/agentics/my-workflow --host-repo my-trial  # Custom host repo
```

---

#### 2. `pr transfer` Defines `-v/--verbose` as a Local Flag

**Command Affected**: `gh aw pr transfer`
**Priority**: Medium
**Type**: Inconsistent flag inheritance

**Current Output** (from running `./gh-aw pr transfer --help`):
```
Flags:
  -h, --help          help for transfer
  -r, --repo string   Target repository ([HOST/]owner/repo format). Defaults to current repository
  -v, --verbose       Verbose output

Global Flags:
      --banner   Display ASCII logo banner with purple GitHub color theme
```

**Expected** (consistent with all other commands, e.g., `disable --help`):
```
Flags:
  -h, --help          help for disable
  -r, --repo string   Target repository ([HOST/]owner/repo format). Defaults to current repository

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

**Issue**: `pr transfer` registers `verbose` as a local flag via `cmd.Flags().BoolP("verbose", "v", false, "Verbose output")` in `pkg/cli/pr_command.go` (line 101), while every other command inherits `--verbose` from the root's `PersistentFlags`. Consequences:
1. The description is shorter: `"Verbose output"` vs the standard `"Enable verbose output showing detailed information"`
2. The flag appears under `Flags:` rather than `Global Flags:`
3. `gh aw pr -v transfer ...` (verbose before subcommand) would NOT work as expected

**Suggested Fix**: Remove the local verbose flag from `pr_command.go` and let the command inherit the global `--verbose` flag. The `verbose` value should be read from the root command's persistent flag.

---

#### 3. All Subcommand Usage Lines Show `gh (cmd)` Instead of `gh aw (cmd)`

**Commands Affected**: All subcommands (`add`, `audit`, `compile`, `disable`, `enable`, `init`, `logs`, `mcp`, `mcp add`, `mcp inspect`, `mcp list`, `mcp list-tools`, `mcp-server`, `new`, `pr`, `pr transfer`, `remove`, `run`, `status`, `trial`, `update`, `version`, `fix`, `list`, `validate`, `completion`, `hash-frontmatter`, `checks`, `health`, `secrets`, `upgrade`, `project`)
**Priority**: Low
**Type**: Inconsistent usage display

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

**Expected**:
```
Usage:
  gh aw audit (run-id) [flags]
```

**Issue**: The main command's help correctly shows `gh aw [flags]`, but all subcommand `Usage:` lines omit the `aw` prefix. A user reading `gh audit (run-id)` would type that verbatim and get an error since the correct invocation is `gh aw audit (run-id)`. The root command `Use` field is `"gh aw"`, but cobra renders subcommands with only their parent's name (`"gh"`), not the full path.

**Suggested Fix**: Set each subcommand's `Use` field to include `aw` (e.g., `"aw audit (run-id)"`) or configure cobra to use the full command path in usage output.

---

#### 4. `secrets bootstrap` Missing Examples Section

**Command Affected**: `gh aw secrets bootstrap`
**Priority**: Low
**Type**: Missing documentation

**Current Output** (from running `./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.

This command:
- Discovers all workflow files in .github/workflows/
- Analyzes required secrets for each workflow's engine
- Checks which secrets already exist in the repository
- Interactively prompts for missing required secrets (unless --non-interactive)

Only required secrets are prompted for. Optional secrets are not shown.

For full details, including precedence rules, see the GitHub Tokens
reference in the documentation.

Usage:
  gh secrets bootstrap [flags]

Issue: secrets bootstrap has no Examples: section, unlike almost all other commands. The docs/src/content/docs/setup/cli.md documentation does include examples:

gh aw secrets bootstrap
gh aw secrets bootstrap --engine copilot
gh aw secrets bootstrap --non-interactive
```

These should be added to the command's help text for consistency.

**Suggested Fix**: Add an `Examples:` field to the `secrets bootstrap` cobra command:
```
gh aw secrets bootstrap                                  # Analyze all workflows and prompt for missing secrets
gh aw secrets bootstrap --engine copilot                 # Check only Copilot secrets
gh aw secrets bootstrap --non-interactive                # Display missing secrets without prompting

Generated by CLI Consistency Checker

• expires on Feb 27, 2026, 1:39 PM UTC