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

[github-actions]

Summary

Automated CLI consistency inspection found 8 inconsistencies in command help text and flag behavior that should be addressed for better user experience and documentation clarity.

Breakdown by Severity

• High: 2 (Breaks expected behavior / confusing semantics)
• Medium: 3 (Misleading or incomplete documentation)
• Low: 3 (Minor inconsistencies)

Issue Categories

1. --repo flag semantic inconsistency (2 commands)

   • In add and trial, --repo means something different from all other commands
   • Affects: add, trial

2. Flag documentation gaps (2 commands)

   • health --days restricts values silently; upgrade --no-fix name doesn't reflect behavior
   • Affects: health, upgrade

3. Minor help text issues (4 commands)

   • Cobra rendering artifact, asymmetric flags, capitalization, terminology
   • Affects: init, logs, pr transfer

Inspection Details

• Total Commands Inspected: 32 (all top-level + all subcommands)
• Commands with Issues: 7
• Date: 2026-03-16
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Examples in help text are accurate and well-formatted
• Global flags (--banner, -v/--verbose, -h/--help) are consistent across all commands
• workflow-id format description is consistent across all applicable commands
• Subcommand structure (mcp, pr, secrets, project, completion) is coherent
• Documentation in docs/src/content/docs/setup/cli.md covers all major commands

⚠️ Issues found:

• --repo flag semantics differ between add/trial and all other commands
• health --days silently rejects non-standard values
• upgrade --no-fix flag name understates what it skips
• init --codespaces renders an unusual default value
• Minor capitalization and terminology inconsistencies

Detailed Findings

1. add command: --repo means "source repository", opposite of convention

Commands Affected: add
Priority: High
Type: Flag semantic inconsistency

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

  -r, --repo string                Source repository containing workflows (owner/repo format)
```

In every other command that uses `--repo`:
```
  -r, --repo string   Target repository ([HOST/]owner/repo format). Defaults to current repository
```

**Issue**: In `add`, `-r, --repo` designates the **source** repository to fetch workflows from. In all other commands (audit, compile, disable, enable, health, logs, run, secrets, status, trial, etc.), `-r, --repo` designates the **target** repository where the command operates. A user familiar with the convention would pass `--repo myorg/myrepo` to `add` expecting to install into `myorg/myrepo`, but instead it sets the workflow source.

**Suggested Fix**: Rename the flag to `-s, --source` or `--source-repo` in the `add` command, and update the description accordingly. The `add` command's operation target is implicitly the current repository.

---

### 2. `trial` command: `--repo` is an alias for `--host-repo`, not target

**Commands Affected**: `trial`
**Priority**: High
**Type**: Flag semantic inconsistency

**Current Output** (from running `./gh-aw trial --help`):
```
      --repo string                     Alias for --host-repo
      --host-repo string                Custom host repository slug (defaults to '(username)/gh-aw-trial'). Use '.' for current repository
```

**Issue**: In `trial`, `--repo` is a convenience alias for `--host-repo` (the trial execution host), not the standard "target repository (defaults to current)" used in all other commands. Additionally, `trial` already has `-s, --logical-repo` for the simulated target repo, so `--repo` serving as `--host-repo` alias creates three different "repo" concepts in one command that don't align with the rest of the CLI.

**Suggested Fix**: Consider deprecating `--repo` as an alias in `trial` to reduce confusion, or add a clear note in the description that `--repo` here is NOT the standard target repository flag.

---

### 3. `health` command: `--days` silently restricts to only three values

**Commands Affected**: `health`
**Priority**: Medium
**Type**: Misleading flag documentation

**Current Output** (from running `./gh-aw health --help`):
```
      --days int          Number of days to analyze (7, 30, or 90) (default 7)
```

**Issue**: The flag type shows as `int`, which implies any integer is valid. In reality, only 7, 30, or 90 are accepted:
```
$ ./gh-aw health --days 14
Error: invalid days value: 14. Must be 7, 30, or 90
```
Users will not know this restriction until they encounter the runtime error.

**Suggested Fix**: Update the flag description to make the restriction more prominent, e.g.: `"Number of days to analyze. Must be one of: 7, 30, or 90 (default 7)"`. Alternatively, use a string enum approach similar to `--engine` to validate at flag parse time with cobra.

---

### 4. `upgrade` command: `--no-fix` flag name understates its effect

**Commands Affected**: `upgrade`
**Priority**: Medium
**Type**: Misleading flag name

**Current Output** (from running `./gh-aw upgrade --help`):
```
      --no-fix                Skip applying codemods, action updates, and compiling workflows (only update agent files)
```

**Issue**: The flag is named `--no-fix`, suggesting it only skips the codemods/fix step. But its description reveals it also skips action updates and workflow compilation — leaving only agent file updates. The name is a partial description of the behavior.

**Suggested Fix**: Either rename to `--agent-only` to match the behavior description "(only update agent files)", or update the description to lead with what it does (not skips): e.g., `"Update agent files only, skipping codemods, action updates, and compilation"`.

---

### 5. `init` command: `--codespaces` flag shows confusing default rendering

**Commands Affected**: `init`
**Priority**: Medium
**Type**: Help text rendering artifact

**Current Output** (from running `./gh-aw init --help`):
```
      --codespaces string[=" "]   Create devcontainer.json for GitHub Codespaces...
```

**Issue**: The `[=" "]` in the flag type is Cobra's way of rendering an optional-value string flag (where `NoOptDefVal` is set to `" "` — a space character). To users, this looks like a typo or rendering bug.

**Suggested Fix**: The code comment explains the space is used internally for detection (`// Trim the codespace repos string (NoOptDefVal uses a space)`). One option is to add a usage hint that removes the confusion: change the type display or add a usage note like `string (optional value)`. Alternatively, restructure the flag to avoid this Cobra rendering artifact, e.g., using a boolean `--codespaces` combined with `--codespaces-repos`.

---

### 6. `logs` command: `--no-staged` has no `--staged` counterpart

**Commands Affected**: `logs`
**Priority**: Low
**Type**: Asymmetric flag pair

**Current Output** (from running `./gh-aw logs --help`):
```
      --firewall              Filter to only runs with firewall enabled
      --no-firewall           Filter to only runs without firewall enabled
      --no-staged             Filter out staged workflow runs (exclude runs with staged: true in aw_info.json)
```

**Issue**: The `--firewall`/`--no-firewall` pair provides symmetric positive and negative filters. However, `--no-staged` has no corresponding `--staged` flag. A user wishing to filter for *only* staged runs has no direct flag.

**Suggested Fix**: Add a `--staged` flag to filter runs with `staged: true`, making the flag pair symmetric with `--firewall`/`--no-firewall`.

---

### 7. `init` command: lowercase "github" and "playwright" in description

**Commands Affected**: `init`
**Priority**: Low
**Type**: Capitalization inconsistency

**Current Output** (from running `./gh-aw init --help`):
```
To create, update or debug automated agentic actions using github, playwright, and other tools, load the .github/agents/agentic-workflows.agent.md (applies to .github/workflows/*.md)
```

**Issue**: "github" and "playwright" should be capitalized as proper nouns: "GitHub" and "Playwright".

**Suggested Fix**: Change to "To create, update or debug automated agentic actions using GitHub, Playwright, and other tools, load the `.github/agents/agentic-workflows.agent.md`..."

---

### 8. `pr transfer` command: "body" vs "description" terminology inconsistency

**Commands Affected**: `pr transfer`
**Priority**: Low
**Type**: Terminology inconsistency

**Current Output** (from running `./gh-aw pr transfer --help`):
```
Transfer a pull request from one repository to another.

This command fetches the pull request details, applies the changes as a single commit,
and creates a new pull request in the target repository with the same title and body.

The command will:
1. Fetch the PR details (title, body, changes)
2. Apply changes as a single squashed commit
3. Create a new PR in the target repository
4. Copy the original title and description

Issue: Item 4 says "Copy the original title and description" while the opening sentence says "same title and body". The PR field is called "body" in GitHub API terms, but both words are used in the same help text.

Suggested Fix: Use "body" consistently throughout, or align to the GitHub web UI term "description" — just pick one and apply it throughout the help text.

Generated by CLI Consistency Checker · ◷

• expires on Mar 18, 2026, 1:45 PM UTC