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

[github-actions]

Summary

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

All commands were built from source (make build) and inspected by running --help on every command and subcommand (30 total).

Breakdown by Severity

• High: 0 (Breaks functionality)
• Medium: 1 (Inconsistent formatting / confusing output)
• Low: 2 (Minor inconsistencies)

Issue Categories

1. Missing blank lines in help text (1 command)

   • Paragraphs in disable Long description are not separated by blank lines, making the text hard to read and inconsistent with enable.

2. Missing period / trailing whitespace (2 commands)

   • trial intro paragraph is missing a terminating period.
   • project new has trailing spaces on one example line.

Inspection Details

• Total Commands Inspected: 30
• Commands with Issues: 3 (disable, trial, project new)
• Date: 2026-03-11
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency across all commands (-h/--help, -v/--verbose, -r/--repo, -e/--engine, etc.)
• Example formatting and accuracy
• Subcommand availability and descriptions
• Short descriptions (all under 80 chars, no trailing periods)
• Global flags consistency
• enable / disable behavior description accuracy
• All 4 MCP subcommands, pr transfer subcommand
• secrets, completion, upgrade, health, checks, validate, fix, list, project commands

⚠️ Issues found:

• disable – missing blank-line separators between Long description paragraphs
• trial – missing period at end of introductory paragraph
• project new – trailing whitespace in example line

Detailed Findings

1. disable — Missing blank lines between Long description paragraphs

Command Affected: gh aw disable
Priority: Medium
Type: Formatting inconsistency

Current output (from ./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.
You can provide either the workflow-id (e.g., 'ci-doctor') or the full filename (e.g., 'ci-doctor.md').

Source location: cmd/gh-aw/main.go, lines 209–211:

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 + `

Issue: All three sentences/paragraphs are concatenated without blank lines. Compare with enable, which renders correctly with blank lines separating each paragraph, because it uses \n\n before WorkflowIDExplanation.

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 + `
```

---

#### 2. `trial` — Missing period at end of introductory paragraph

**Command Affected**: `gh aw trial`
**Priority**: Low
**Type**: Punctuation

**Current output** (from `./gh-aw trial --help`):
```
This command creates a temporary private repository in your GitHub space, installs the specified
workflow(s) from their source repositories, and runs them in "trial mode" to capture safe outputs without
making actual changes to the "simulated" host repository

Source location: pkg/cli/trial_command.go, line 79:

making actual changes to the "simulated" host repository

Issue: The introductory paragraph ends without a period, unlike all other command descriptions.

Suggested fix: Add a period at the end of the sentence:

making actual changes to the "simulated" host repository.
```

---

#### 3. `project new` — Trailing whitespace in example line

**Command Affected**: `gh aw project new`
**Priority**: Low
**Type**: Formatting (trailing whitespace)

**Current output** (from `./gh-aw project new --help`):
```
  gh aw project new "Team Board" --owner myorg                         # Create org project  
```

**Source location**: `pkg/cli/project_command.go`, line 78 (confirmed with `cat -A`):
```
  gh aw project new "Team Board" --owner myorg                         # Create org project  $

Issue: Two trailing spaces after # Create org project on this line. Other examples in the same block have no trailing whitespace.

Suggested fix: Remove the two trailing spaces:

  gh aw project new "Team Board" --owner myorg                         # Create org project

Generated by CLI Consistency Checker · ◷

• expires on Mar 13, 2026, 1:39 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-03-13T13:39:08.535Z.

Closed by Workflow