Skip to content

[cli-consistency] CLI Consistency Issues - 2026-03-02 #19222

@github-actions

Description

@github-actions

Summary

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

Breakdown by Severity

  • High: 1 (Outdated information breaks user expectations)
  • Medium: 3 (Inconsistent terminology or missing behavior descriptions)
  • Low: 1 (Minor omission)

Inspection Details

  • Total Commands Inspected: 30 (--help run for every command and subcommand)
  • Commands with Issues: 5
  • Date: 2026-03-02
  • Method: Executed all CLI commands with --help flags, ran --list-codemods, and compared with documentation in docs/src/content/docs/setup/cli.md

Findings Summary

No issues found in these areas:

  • Global flags consistency (-v, -h, --banner present everywhere)
  • Flag naming conventions (consistent across similar commands)
  • Example formatting and accuracy
  • Documentation URLs (confirmed github.github.com is the intentional docs domain per astro.config.mjs)
  • mcp, pr, secrets, project subcommand structures
  • add, compile, run, logs, audit, status, health, update, upgrade core commands

⚠️ Issues found:

  • fix help has severely outdated hardcoded codemod list
  • --repeat flag description is ambiguous in run and trial
  • disable summary description and detailed help disagree on behavior
  • project new help has mixed whitespace formatting
Detailed Findings

1. fix --help "Available codemods" section is severely outdated

Commands Affected: fix
Priority: High
Type: Outdated information

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

Available codemods:
  • timeout-minutes-migration: Replaces 'timeout_minutes' with 'timeout-minutes'
  • network-firewall-migration: Removes deprecated 'network.firewall' field
  • sandbox-false-to-agent-false: Converts 'sandbox: false' to 'sandbox.agent: false'
  • safe-inputs-mode-removal: Removes deprecated 'safe-inputs.mode' field
  • schedule-at-to-around-migration: Converts 'daily at TIME' to 'daily around TIME'
  • delete-schema-file: Deletes deprecated .github/aw/schemas/agentic-workflow.json
  • delete-old-agents: Deletes old workflow-specific .agent.md files from .github/agents/
  • delete-old-templates: Removes old template files from pkg/cli/templates/
```

**Issue**: The hardcoded list in help text lists only 8 codemods, but `./gh-aw fix --list-codemods` shows **24 codemods**. Additionally, two entries in the help text (`delete-old-agents`, `delete-old-templates`) do not appear in the actual codemod registry at all — they were apparently removed but the help text was never updated. Missing from help text (among others): `command-to-slash-command-migration`, `expires-integer-to-string`, `serena-local-to-docker`, `roles-to-on-roles`, `bots-to-on-bots`, `playwright-allowed-domains-migration`, and 16 more.

**Source**: `pkg/cli/fix_command.go` lines 41–49

**Suggested Fix**: Remove the hardcoded "Available codemods" section from the `Long` help text in `fix_command.go` entirely, and replace it with a pointer to `--list-codemods`:

```
This command applies a registry of codemods that automatically update deprecated fields
and migrate to new syntax. Codemods preserve formatting and comments as much as possible.

Use --list-codemods to see all available codemods with descriptions.
```

---

#### 2. `--repeat` flag description is ambiguous (run, trial)

**Commands Affected**: `run`, `trial`
**Priority**: Medium
**Type**: Inconsistent/ambiguous description

**Current Output** (from `./gh-aw run --help` and `./gh-aw trial --help`):
```
      --repeat int              Number of times to repeat running workflows (0 = run once)
```

**With example**:
```
gh aw run daily-perf-improver --repeat 3  # Run 3 times total

Issue: The flag name repeat and phrase "Number of times to repeat" implies additional runs after the first (so --repeat 3 = run once + 3 repeats = 4 total). However, the example --repeat 3 # Run 3 times total indicates it means total count (3 total). The parenthetical (0 = run once) further suggests the default=0 maps to 1 total run, compounding the confusion for new users.

Suggested Fix: Clarify the description to remove ambiguity:

cmd.Flags().Int("repeat", 0, "Total number of times to run the workflow (default: 1 when set to 0)")
```

Or keep the current semantics but update the example comment:
```
gh aw run daily-perf-improver --repeat 3  # Run a total of 3 times
```

And update `trial_command.go:97` similarly.

---

#### 3. `disable` summary description mentions behavior not in detailed help

**Commands Affected**: `disable`
**Priority**: Medium
**Type**: Inconsistency between summary and detailed help

**Current Main Help Summary** (from `./gh-aw --help`):
```
disable     Disable agentic workflows and cancel any in-progress runs
```

**Current Detailed Help** (from `./gh-aw disable --help`):
```
Disable one or more workflows by ID, or all workflows if no IDs are provided.
```

**Issue**: The main help summary says the command "cancel any in-progress runs" but the detailed `--help` for `disable` makes no mention of this behavior. Users who read the detailed help will be unaware of this behavior. If the command does cancel in-progress runs, the detailed help should document it; if it does not, the summary should be corrected.

**Suggested Fix**: If the command does cancel in-progress runs, update the `Short` description in `disable_command.go` to mention it, and add it to the `Long` description with examples. If not, update the main root command's short description to remove the claim.

---

#### 4. `project new` help has mixed tabs and spaces in "Project Setup" section

**Commands Affected**: `project new`
**Priority**: Medium
**Type**: Formatting inconsistency

**Current Output** (from `./gh-aw project new --help`):
```
Project Setup:
	Use --with-project-setup to automatically create:
	- Standard views (Progress Board, Task Tracker, Roadmap)
	- Custom fields (Tracker Id, Worker Workflow, Target Repo, Priority, Size, dates)
  - Enhanced Status field with "Review Required" option
```

**Issue**: The first three lines of the "Project Setup" block use **tab** characters for indentation, but the last line (`- Enhanced Status field...`) uses **spaces**. This renders inconsistently in terminals and violates the whitespace style used in all other help text blocks.

**Suggested Fix**: Use consistent spacing (spaces, not tabs) for the entire `Project Setup` section to match the surrounding help text style.

---

#### 5. `version` command has no description, examples, or long help

**Commands Affected**: `version`
**Priority**: Low
**Type**: Missing documentation

**Current Output** (from `./gh-aw version --help`):
```
Show gh aw extension version information

Usage:
  gh aw version [flags]

Flags:
  -h, --help   help for version
```

**Issue**: The `version` command has no `Long` description, no examples, and no flags beyond `--help`. While simple, at minimum an example would help users understand what information is displayed (e.g., commit SHA, version tag, build date). Most other commands provide at least one example.

**Suggested Fix**: Add a minimal example:
```
Examples:
  gh aw version          # Display version information
  gh aw version --json   # Output version in JSON format (if supported)

Generated by CLI Consistency Checker

  • expires on Mar 4, 2026, 1:36 PM UTC

Metadata

Metadata

Labels

automationclicookieIssue Monster Loves Cookies!documentationImprovements or additions to documentation

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions