Skip to content

[cli-consistency] CLI Consistency Issues - 2026-02-27 #18694

@github-actions

Description

@github-actions

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 --help flags and analyzed actual output

Findings Summary

No issues found in these areas:

  • Flag naming conventions (-r, -e, -d, -j, -o, -v short flags are consistent)
  • Example formatting across commands
  • Long description style and grammar
  • Global flags consistency (--banner, -v/--verbose, -h/--help)
  • disable/enable symmetry
  • mcp subcommand consistency

⚠️ Issues found:

  • project new --help: Mixed tab/space indentation + capitalization inconsistency
  • fix --help: Step 5 missing (with --write flag) qualifier, internal path exposed
  • trial --help: Duplicate default text in --timeout flag
  • upgrade --help: Inaccurate "always" qualifier
  • compile --force: Missing -f short 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

Metadata

Metadata

Assignees

No one assigned

    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