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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0
• Medium: 1 (Inconsistent/misleading description)
• Low: 3 (Minor wording/alignment inconsistencies)

Inspection Details

• Total Commands Inspected: 38 (--help run on all top-level commands + all subcommands)
• Commands with Issues: 4
• Date: 2026-03-13
• Method: Executed all CLI commands with --help flags and analyzed actual output vs source code

Findings Summary

✅ No issues found in these areas:

• Technical accuracy of examples
• Flag naming consistency across commands
• Documentation cross-reference (all commands documented in docs/src/content/docs/setup/cli.md)
• Global flags consistency (-v/--verbose, -h/--help, --banner)
• Typos or grammar errors in long descriptions
• Missing required subcommand help

⚠️ Issues found:

• add-wizard Short vs Long description mismatch (singular vs plural)
• init Short description missing article "the"
• disable/enable example comment alignment off by one character
• run examples inconsistent spacing before # comments

Detailed Findings

1. add-wizard Short Description Says Singular, Command Supports Plural

Commands Affected: add-wizard
Priority: Medium
Type: Inconsistent description (Short vs Long)
File: pkg/cli/add_wizard_command.go:19

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

  add-wizard  Interactively add an agentic workflow with guided setup
```

**Current Output** (from running `./gh-aw add-wizard --help`):
```
Interactively add one or more workflows with guided setup.

Issue: The Short description says "an agentic workflow" (singular), but the command clearly supports adding multiple workflows at once (as stated in the Long description and shown in examples like gh aw add-wizard ./my-workflow.md). The parent --help listing is therefore misleading.

Suggested Fix: Update Short in pkg/cli/add_wizard_command.go to match the Long description:

Short: "Interactively add one or more agentic workflows with guided setup",
```

---

#### 2. `init` Short Description Missing Article "the"

**Commands Affected**: `init`
**Priority**: Low
**Type**: Minor grammar inconsistency
**File**: `pkg/cli/init_command.go:17`

**Current Output** (from running `./gh-aw --help`):
```
  init        Initialize repository for agentic workflows
```

**Current Output** (from running `./gh-aw init --help`):
```
Initialize the repository for agentic workflows by configuring .gitattributes...

Issue: The Short description omits the article "the" ("Initialize repository") while the Long description includes it ("Initialize the repository"). Minor but inconsistent.

Suggested Fix:

Short: "Initialize the repository for agentic workflows",
```

---

#### 3. `disable`/`enable` Example Comment Alignment Off by One

**Commands Affected**: `disable`, `enable`
**Priority**: Low
**Type**: Formatting inconsistency

**Current Output** (from `./gh-aw disable --help`):
```
Examples:
  gh aw disable                    # Disable all workflows
  gh aw disable ci-doctor         # Disable specific workflow
  gh aw disable ci-doctor.md      # Disable specific workflow (alternative format)
  gh aw disable ci-doctor daily   # Disable multiple workflows
  gh aw disable ci-doctor --repo owner/repo  # Disable workflow in specific repository
```

**Issue**: The first example's `#` comment starts at column 36 (20 spaces of padding after `gh aw disable`), while the remaining examples' `#` comments start at column 35 (9, 6, 3 spaces of padding respectively). The first line has one extra trailing space, causing the comments to not align. The same misalignment exists in the `enable` command examples.

**Suggested Fix**: Remove one trailing space from the first example in both `disable` and `enable` commands so all `#` comments align at the same column.

---

#### 4. `run` Examples Inconsistent Spacing Before `#` Comments

**Commands Affected**: `run`
**Priority**: Low
**Type**: Minor formatting inconsistency

**Current Output** (from `./gh-aw run --help`):
```
Examples:
  gh aw run daily-perf-improver --ref main  # Run on specific branch
  gh aw run daily-perf-improver --repeat 3  # Run 4 times total (1 initial + 3 repeats)
  gh aw run daily-perf-improver --enable-if-needed # Enable if disabled, run, then restore state
  gh aw run daily-perf-improver --auto-merge-prs # Auto-merge any PRs created during execution
  gh aw run daily-perf-improver -F name=value -F env=prod  # Pass workflow inputs

Issue: Most examples use two spaces before # (e.g., --ref main #, --repeat 3 #) but --enable-if-needed and --auto-merge-prs use only one space before #. This breaks the visual consistency of the examples block.

Suggested Fix: Add a second space before # on the --enable-if-needed and --auto-merge-prs example lines for visual consistency.

Generated by CLI Consistency Checker · ◷

• expires on Mar 15, 2026, 1:38 PM UTC