[cli-consistency] CLI Consistency Issues - 2026-03-05 #19727
Description
Summary
Automated CLI consistency inspection found 3 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.
Breakdown by Severity
- High: 0 (Breaks functionality)
- Medium: 1 (Confusing/misleading behavior)
- Low: 2 (Minor cosmetic inconsistencies)
Issue Categories
- Help structure inconsistency (1 command) —
secrets bootstrap - Missing blank line in Long description (1 command) —
disable - Inconsistent
--repoflag semantics (1 command) —trial
Inspection Details
- Total Commands Inspected: 32 (
--helprun for every command and subcommand) - Commands with Issues: 3
- Date: 2026-03-05
- Method: Built
./gh-awbinary from source, executed all commands with--helpflags, analyzed actual output and cross-referenced source code
Findings Summary
✅ No issues found in these areas:
- All commands have proper descriptions and examples
- Flag names and short flags are consistent across similar commands
- No typos or grammar errors detected in help text
- Global flags (
--verbose,--help,--banner) are consistent - Documentation in
docs/src/content/docs/setup/cli.mdmatches actual CLI behavior
secrets bootstrap: Examples section displays after Usage (inconsistent ordering)disable: Missing blank line between introductory paragraph and bodytrial:--repoflag has non-standard semantics (alias for--host-repoinstead of "target repository")
Detailed Findings
1. secrets bootstrap — Examples appear AFTER Usage section
Command affected: gh aw secrets bootstrap
Priority: Low
Type: Cosmetic inconsistency in help structure
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...
Usage:
gh aw secrets bootstrap [flags]
Examples:
gh aw secrets bootstrap # Check and set up all required secrets
gh aw secrets bootstrap --non-interactive # Display missing secrets without prompting
gh aw secrets bootstrap --engine copilot # Check secrets for a specific engine
Issue: Examples: section appears after Usage: section. In every other command (e.g., audit, compile, logs, run), examples are embedded in the Long description and appear before Usage:.
Root cause: pkg/cli/tokens_bootstrap.go uses cobra's separate Example: struct field, while all other commands embed examples inline in the Long field. Cobra's default template places the Example field after Usage.
Suggested Fix: Move examples from the cobra Example: field into the Long description, following the same pattern as all other commands:
// Before (tokens_bootstrap.go):
Long: `Analyzes all workflows...`,
Example: ` gh aw secrets bootstrap # ...`,
// After:
Long: `Analyzes all workflows...
Examples:
gh aw secrets bootstrap # Check and set up all required secrets
gh aw secrets bootstrap --non-interactive # Display missing secrets without prompting
gh aw secrets bootstrap --engine copilot # Check secrets for a specific engine`,
// Remove Example field entirely
```
---
#### 2. `disable` — Missing blank line in Long description
**Command affected**: `gh aw disable`
**Priority**: Low
**Type**: Formatting inconsistency
**Current Output** (from running `./gh-aw disable --help`):
```
Disable one or more workflows by ID, or all workflows if no IDs are provided.
Any in-progress runs will be cancelled before disabling.
The workflow-id is the basename of the Markdown file without the .md extension.
```
**Issue**: The second sentence ("Any in-progress runs will be cancelled before disabling.") runs directly into the `WorkflowIDExplanation` without paragraph separation. All other multi-paragraph Long descriptions include blank lines between paragraphs.
**Comparison** (from `./gh-aw enable --help`):
```
Enable one or more workflows by ID, or all workflows if no IDs are provided.
The workflow-id is the basename of the Markdown file without the .md extension.Root cause: In cmd/gh-aw/main.go, the disableCmd.Long is:
Long: `Disable one or more workflows by ID, or all workflows if no IDs are provided.
Any in-progress runs will be cancelled before disabling.
` + cli.WorkflowIDExplanation + `There is no blank line after the extra sentence.
Suggested Fix:
Long: `Disable one or more workflows by ID, or all workflows if no IDs are provided.
Any in-progress runs will be cancelled before disabling.
` + cli.WorkflowIDExplanation + `
```
---
#### 3. `trial` — `--repo` flag has inconsistent semantics
**Command affected**: `gh aw trial`
**Priority**: Medium
**Type**: Potentially misleading flag behavior
**Current Output** (from running `./gh-aw trial --help`):
```
--repo string Alias for --host-repo
--host-repo string Custom host repository slug (defaults to '(username)/gh-aw-trial'). Use '.' for current repository
-s, --logical-repo string The repo we're simulating the execution for...Issue: In every other gh aw command that accepts --repo (e.g., disable, enable, run, logs, status, health, checks), the flag means "target/production repository" and is documented as:
Target repository ([HOST/]owner/repo format). Defaults to current repository
In trial, --repo is documented as "Alias for --host-repo" — the ephemeral sandbox repository, not the production target. This is the opposite of what users familiar with the rest of the CLI would expect.
Evidence from cmd/gh-aw/main.go and pkg/cli/trial_command.go:
cmd.Flags().String("repo", "", "Alias for --host-repo")
cmd.MarkFlagsMutuallyExclusive("host-repo", "repo")Suggested Fix: Consider one of:
- Remove the
--repoalias entirely, requiring users to use--host-repoexplicitly for the sandbox repo (breaking change, but more consistent) - Add a note in the
--repoflag description explicitly warning that it behaves differently from other commands:"Alias for --host-repo (NOTE: unlike other commands, this does not target a production repository)" - Keep as-is but add a callout in the help text warning users about the difference
Generated by CLI Consistency Checker · ◷
- expires on Mar 7, 2026, 1:39 PM UTC