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

[github-actions]

Summary

Automated CLI consistency inspection found 8 inconsistencies across 41 commands/subcommands. All commands were inspected by running ./gh-aw <command> --help against the built binary and cross-referencing with docs/src/content/docs/setup/cli.md.

Breakdown by Severity

• High: 1 (Documentation inaccuracy)
• Medium: 3 (Short flag collisions, semantic inconsistency)
• Low: 4 (Minor inconsistencies)

Issue Categories

1. Documentation vs CLI mismatch (1 command) — add-wizard
2. Short flag collisions (2 cases) — -w and -o
3. --dir semantic inconsistency (6+ commands) — different meanings across command groups
4. Minor style/consistency issues (4 items) — format ordering, missing flags, implementation leakage, dry-run pattern

Inspection Details

• Total Commands Inspected: 41 (including all subcommands)
• Commands with Issues: 9
• Date: 2026-04-03
• Method: Executed all CLI commands with --help flags against built binary; cross-referenced with documentation

Findings Summary

✅ No issues found in these areas:

• All commands have proper --help flags
• Global flags (-v, -e, -r, -j, -h) are consistent across all commands
• Example formatting is consistent and helpful throughout
• Command descriptions are clear and free of typos/grammar errors
• All documented commands exist in the binary
• disable/enable command pair is symmetric and consistent
• audit diff/audit report subcommands are well-structured
• mcp subcommand group is internally consistent

⚠️ Issues found:

• Documentation incorrectly claims add-wizard supports --create-pull-request
• Short flag -w has two different meanings (--watch vs --workflow)
• Short flag -o collision in project new (uses -o for --owner vs convention of -o for --output)
• --dir flag means different things in add/add-wizard vs other commands

Detailed Findings

1. Documentation incorrectly lists add-wizard as supporting --create-pull-request

Commands Affected: add-wizard
Priority: High
Type: Documentation inaccuracy

Current CLI Output (from ./gh-aw add-wizard --help):

Flags:
  -d, --dir string          Subdirectory under .github/workflows/
  -e, --engine string       Override AI engine
  -h, --help                Show help for gh aw add-wizard
      --no-gitattributes    Skip updating .gitattributes file
      --no-stop-after       Remove any stop-after field from the workflow
      --skip-secret         Skip the API secret prompt
      --stop-after string   Override stop-after value in the workflow
```

**Issue**: The file `docs/src/content/docs/setup/cli.md` states in the GHES section:
> *"Commands that support `--create-pull-request` (such as `gh aw add`, **`gh aw add-wizard`**, `gh aw init`, `gh aw update`, and `gh aw upgrade`) automatically detect the enterprise host..."*

But `add-wizard` does **not** have a `--create-pull-request` flag. The `add-wizard` "Options" section in the same doc correctly omits this flag, but the GHES paragraph is wrong.

**Suggested Fix**: Remove `gh aw add-wizard` from the list in the GHES paragraph in `docs/src/content/docs/setup/cli.md`.

---

#### 2. Short flag `-w` collision: `--watch` vs `--workflow`

**Commands Affected**: `compile` (uses `-w` for `--watch`), `audit report` (uses `-w` for `--workflow`)
**Priority**: Medium
**Type**: Short flag inconsistency

**Current CLI Output** from `./gh-aw compile --help`:
```
-w, --watch   Watch for changes to workflow files and recompile automatically
```

**Current CLI Output** from `./gh-aw audit report --help`:
```
-w, --workflow string   Filter by workflow name or filename
```

**Issue**: The short flag `-w` maps to `--watch` in `compile` but to `--workflow` in `audit report`. The codebase convention (per `AGENTS.md`) reserves `-w` for watch. Users who muscle-memory `-w` for watch may be surprised when it filters by workflow name in `audit report`.

**Suggested Fix**: Change `audit report` to use a different short flag or no short flag for `--workflow` (e.g., remove the `-w` shorthand since `-w` is reserved for watch).

Source: `pkg/cli/audit_report_cross_run_command.go:81` and `cmd/gh-aw/main.go:660`.

---

#### 3. Short flag `-o` collision: `--output` vs `--owner`

**Commands Affected**: Most commands (use `-o` for `--output`), `project new` (uses `-o` for `--owner`)
**Priority**: Medium
**Type**: Short flag inconsistency

**Current CLI Output** from `./gh-aw project new --help`:
```
-o, --owner string   Project owner: '`@me`' for current user or organization name (required)
```

**Issue**: The project-wide convention (defined in `pkg/cli/flags.go:26`) reserves `-o` as the short flag for `--output`. The `project new` command breaks this convention by using `-o` for `--owner`. Users expecting `-o output-dir` in `project new` would accidentally set the owner.

**Suggested Fix**: Remove the `-o` shorthand from `project new`'s `--owner` flag (or change to a different letter). Source: `pkg/cli/project_command.go:104`.

---

#### 4. `--dir` flag has different semantics across command groups

**Commands Affected**: `add`, `add-wizard` (one meaning) vs `compile`, `validate`, `fix`, `upgrade`, `update`, `list` (different meaning)
**Priority**: Medium
**Type**: Semantic inconsistency

**Current CLI Output** from `./gh-aw add --help`:
```
-d, --dir string   Subdirectory under .github/workflows/ (e.g., 'shared' creates .github/workflows/shared/)
```
Example: `gh aw add githubnext/agentics/ci-doctor --dir shared   # Add to .github/workflows/shared/`

**Current CLI Output** from `./gh-aw compile --help`:
```
-d, --dir string   Workflow directory (default: .github/workflows)
```
Example: `gh aw compile --dir custom/workflows  # Compile from custom directory`

**Issue**: For `add` and `add-wizard`, `--dir` is a *subdirectory appended under* `.github/workflows/` (so `--dir shared` yields `.github/workflows/shared/`). For `compile`, `validate`, `fix`, `upgrade`, `update`, and `list`, `--dir` is the *complete replacement path* for the workflow directory. A user who passes `--dir shared` to `compile` would compile from `./shared/` rather than `.github/workflows/shared/`.

**Suggested Fix**: Consider renaming the flag in `add`/`add-wizard` to `--subdir` to make the distinction explicit, or update the flag descriptions more prominently to warn about this behavioral difference.

---

#### 5. `--format` option ordering inconsistency between `audit diff` and `audit report`

**Commands Affected**: `audit diff`, `audit report`
**Priority**: Low
**Type**: Minor style inconsistency

**Current CLI Output** from `./gh-aw audit diff --help`:
```
--format string   Output format: pretty, markdown (default "pretty")
```

**Current CLI Output** from `./gh-aw audit report --help`:
```
--format string   Output format: markdown, pretty (default "markdown")
```

**Issue**: The ordering of format options in the flag description differs. `audit diff` lists `pretty, markdown` while `audit report` lists `markdown, pretty`. Although both have different defaults (by design), the option order should be consistent — conventionally listed alphabetically or with the default first.

**Suggested Fix**: Standardize to list options with the default first: `audit diff` → `"pretty, markdown"` (already correct), `audit report` → `"markdown, pretty"` (already correct). Alternatively, list both alphabetically as `"markdown, pretty"` in both.

---

#### 6. `add-wizard` missing several flags available in `add`

**Commands Affected**: `add-wizard`
**Priority**: Low
**Type**: Missing flags

**Flags in `add` but NOT in `add-wizard`**:
- `--append string` — Append extra content to the end of the workflow on installation
- `--disable-security-scanner` — Disable security scanning of workflow markdown content  
- `--force / -f` — Overwrite existing workflow files without confirmation
- `--name / -n string` — Specify name for the added workflow

**Issue**: `add-wizard` is documented as the interactive alternative to `add`, but is missing these useful flags. In particular, `--force` and `--disable-security-scanner` could be useful even in interactive mode.

**Suggested Fix**: Evaluate whether `--append`, `--disable-security-scanner`, `--force`, and `--name` should be added to `add-wizard`.

---

#### 7. `gh aw run` leaks internal implementation detail

**Commands Affected**: `run`
**Priority**: Low
**Type**: Help text quality

**Current CLI Output** from `./gh-aw run --help`:
```
This command only works with workflows that have workflow_dispatch triggers.
It executes 'gh workflow run <workflow-lock-file>' to trigger each workflow on GitHub Actions.
```

**Issue**: Mentioning the internal implementation (`gh workflow run <workflow-lock-file>`) exposes a leaky abstraction. The lock file naming convention and the use of `gh workflow run` are implementation details. If the implementation changes, this text will become misleading. Users don't need to know the underlying mechanism.

**Suggested Fix**: Replace with: *"It uses the GitHub Actions API to trigger each workflow on GitHub Actions."*

---

#### 8. `fix --write` pattern inconsistent with `run --dry-run` / `trial --dry-run`

**Commands Affected**: `fix`, `run`, `trial`
**Priority**: Low
**Type**: UX pattern inconsistency

**Current CLI Output** from `./gh-aw fix --help`:
```
--write   Write changes to files (without this flag, no changes are made)
```

**Current CLI Output** from `./gh-aw run --help` and `./gh-aw trial --help`:
```
--dry-run   Validate workflow without actually triggering execution on GitHub Actions
--dry-run   Show what would be done without making any changes

Issue: run and trial use --dry-run as an explicit opt-in for non-destructive preview mode (the default is to apply changes). fix inverts this pattern: the default is dry-run and --write opts into applying changes. This asymmetry can confuse users who expect --dry-run to be the safe preview flag across all commands.

Suggested Fix: Consider adding --dry-run as an alias for the default behavior of fix (no-op without --write) to make the pattern more discoverable, or at minimum update the fix help text to call out that it defaults to dry-run mode more prominently.

Generated by CLI Consistency Checker · ● 2.4M · ◷

• expires on Apr 5, 2026, 1:45 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot coding agent.

The Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · ● 416K · ◷

[copilot-swe-agent]

The agent encountered an error and was unable to start working on this issue: This may be caused by a repository ruleset violation. See granting bypass permissions for the agent, or please contact support if the issue persists. (Request id: 1181:3D716D:89B3B2:2216593:69CFDC0C)