-
Notifications
You must be signed in to change notification settings - Fork 278
Description
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 (
--helprun for every command and subcommand) - Commands with Issues: 5
- Date: 2026-03-02
- Method: Executed all CLI commands with
--helpflags, ran--list-codemods, and compared with documentation indocs/src/content/docs/setup/cli.md
Findings Summary
✅ No issues found in these areas:
- Global flags consistency (
-v,-h,--bannerpresent everywhere) - Flag naming conventions (consistent across similar commands)
- Example formatting and accuracy
- Documentation URLs (confirmed
github.github.comis the intentional docs domain perastro.config.mjs) mcp,pr,secrets,projectsubcommand structuresadd,compile,run,logs,audit,status,health,update,upgradecore commands
fixhelp has severely outdated hardcoded codemod list--repeatflag description is ambiguous inrunandtrialdisablesummary description and detailed help disagree on behaviorproject newhelp 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