-
Notifications
You must be signed in to change notification settings - Fork 278
Description
Summary
Automated CLI consistency inspection found 9 inconsistencies in command help text across the gh aw CLI tool.
Breakdown by Severity
- High: 0
- Medium: 5 (confusing/misleading or incorrect documentation)
- Low: 4 (minor inconsistencies)
Inspection Details
- Total Commands Inspected: 30 (all top-level commands + subcommands with
--help) - Commands with Issues: 5 (
project new,fix,trial,upgrade,compile) - Date: 2026-02-27
- Method: Executed all CLI commands with
--helpflags and analyzed actual output
Findings Summary
✅ No issues found in these areas:
- Flag naming conventions (
-r,-e,-d,-j,-o,-vshort flags are consistent) - Example formatting across commands
- Long description style and grammar
- Global flags consistency (
--banner,-v/--verbose,-h/--help) disable/enablesymmetrymcpsubcommand consistency
project new --help: Mixed tab/space indentation + capitalization inconsistencyfix --help: Step 5 missing(with --write flag)qualifier, internal path exposedtrial --help: Duplicate default text in--timeoutflagupgrade --help: Inaccurate "always" qualifiercompile --force: Missing-fshort flag vs other commands
Detailed Findings
1. project new — Mixed Tab/Space Indentation in Help Text
Command Affected: gh aw 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**: Lines 2–4 use hard tabs (`\t`) for indentation; line 5 uses two spaces. This causes the last bullet to render at a different alignment in terminals and docs.
**Source**: `pkg/cli/project_command.go` lines 71–75
**Suggested Fix**: Use consistent two-space indentation throughout the "Project Setup" block.
---
#### 2. `project new` — Inconsistent Capitalization in List Items
**Command Affected**: `gh aw project new`
**Priority**: Medium
**Type**: Grammar/style inconsistency
**Current Output** (from `./gh-aw project new --help`):
```
- Custom fields (Tracker Id, Worker Workflow, Target Repo, Priority, Size, dates)
```
**Issue**: All items in the parenthesized list use Title Case (`Tracker Id`, `Worker Workflow`, `Target Repo`, `Priority`, `Size`) except the last one (`dates`, lowercase). Should be `Dates` or all items lowercased for consistency.
**Source**: `pkg/cli/project_command.go` line 73
**Suggested Fix**: Change `dates` → `Dates` to match the title-case style of the other items.
---
#### 3. `fix` — Step 5 Missing `(with --write flag)` Qualifier
**Command Affected**: `gh aw fix`
**Priority**: Medium
**Type**: Misleading documentation
**Current Output** (from `./gh-aw fix --help`):
```
The command will:
1. Scan workflow files for deprecated fields
2. Apply relevant codemods to fix issues
3. Report what was changed in each file
4. Write updated files back to disk (with --write flag)
5. Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists
6. Delete old template files from pkg/cli/templates/ (with --write flag)
7. Delete old workflow-specific .agent.md files from .github/agents/ (with --write flag)
```
**Issue**: Steps 4, 6, and 7 explicitly note `(with --write flag)`, but step 5 does not — implying the schema file deletion may happen in dry-run mode. The code (`pkg/cli/fix_command.go` line 221) correctly gates deletion behind `if write`, so the help text is just incorrect.
**Suggested Fix**: Change step 5 to: `Delete deprecated .github/aw/schemas/agentic-workflow.json file if it exists (with --write flag)`
---
#### 4. `fix` — Internal Implementation Path Exposed in Help Text
**Command Affected**: `gh aw fix`
**Priority**: Medium
**Type**: Implementation detail leak
**Current Output** (from `./gh-aw fix --help`):
```
Available codemods:
• delete-old-templates: Removes old template files from pkg/cli/templates/
...
6. Delete old template files from pkg/cli/templates/ (with --write flag)
```
**Issue**: `pkg/cli/templates/` is a Go source tree path that is only meaningful to contributors, not end users. End users cannot navigate to or interact with that path in the CLI.
**Suggested Fix**: Replace `pkg/cli/templates/` with something user-facing, like `(internal templates)` or simply remove the parenthetical path.
---
#### 5. `trial` — Duplicate Default Text in `--timeout` Flag
**Command Affected**: `gh aw trial`
**Priority**: Medium
**Type**: Duplicate text / rendering bug
**Current Output** (from `./gh-aw trial --help`):
```
--timeout int Execution timeout in minutes (default: 30) (default 30)
Issue: The flag description includes (default: 30) hardcoded in the description string, and cobra/pflag appends (default 30) automatically because the Go default value is 30. This results in the redundant (default: 30) (default 30) text shown to users.
Source: pkg/cli/trial_command.go line 188:
cmd.Flags().Int("timeout", 30, "Execution timeout in minutes (default: 30)")Suggested Fix: Remove the (default: 30) from the flag description string since cobra adds it automatically:
cmd.Flags().Int("timeout", 30, "Execution timeout in minutes")
```
---
#### 6. `upgrade` — Misleading "Always" Qualifier
**Command Affected**: `gh aw upgrade`
**Priority**: Low
**Type**: Inaccurate description
**Current Output** (from `./gh-aw upgrade --help`):
```
This command always upgrades all Markdown files in .github/workflows.
```
**Issue**: This statement is inaccurate when `--dir` is specified, which changes the workflow directory. The qualifier "always" and "in .github/workflows" are both only true for the default case.
**Source**: `pkg/cli/upgrade_command.go` line 64
**Suggested Fix**: `This command upgrades all Markdown files in the workflow directory (default: .github/workflows).`
---
#### 7. `compile --force` Missing `-f` Short Flag
**Command Affected**: `gh aw compile`
**Priority**: Low
**Type**: Flag inconsistency
**Current Output** (from `./gh-aw compile --help`):
```
--force Force overwrite of existing dependency files (e.g., dependabot.yml)
```
**Issue**: `--force` in `gh aw new` and `gh aw update` both have `-f` as the short flag, but `gh aw compile --force` does not. Users accustomed to `-f` for force-overwrite may be surprised.
**Suggested Fix**: Add `-f` as a short flag alias for `--force` in the `compile` command, consistent with `new` and `update`.
---
#### 8. Documentation: `secrets bootstrap --owner` Flag Not Present in CLI
**Command Affected**: `gh aw secrets bootstrap`
**Priority**: Low
**Type**: Documentation vs CLI mismatch
**Issue**: The CLI documentation (`docs/src/content/docs/setup/cli.md`) lists `--owner` as an option for `secrets bootstrap`:
> **Options:** `--engine` (copilot, claude, codex), `--non-interactive`, `--owner`, `--repo`
But running `./gh-aw secrets bootstrap --help` shows no `--owner` flag. The flag list is: `--engine`, `--non-interactive`, `--repo`.
**Suggested Fix**: Remove `--owner` from the documented options for `secrets bootstrap` in `docs/src/content/docs/setup/cli.md`.
---
#### 9. `AGENTS.md` MCP Registry URL Outdated
**Command Affected**: `gh aw mcp add`
**Priority**: Low
**Type**: Documentation mismatch
**Issue**: `AGENTS.md` states:
> **Default MCP Registry**: Uses GitHub's MCP registry at `https://api.mcp.github.com/v0` by default.
But `./gh-aw mcp add --help` shows:
```
Registry URL defaults to: https://api.mcp.github.com/v0.1
...
--registry string MCP registry URL (default: https://api.mcp.github.com/v0.1)The actual default in the CLI is v0.1, not v0.
Suggested Fix: Update AGENTS.md to use https://api.mcp.github.com/v0.1.
Generated by CLI Consistency Checker
- expires on Mar 1, 2026, 1:36 PM UTC