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

[github-actions]

Summary

Automated CLI consistency inspection of 40 commands/subcommands found 11 inconsistencies in command help text. These range from unclear terminology to minor redundancies and documentation mismatches.

Breakdown by Severity

• High: 0 (no functionality-breaking issues)
• Medium: 3 (confusing/misleading descriptions)
• Low: 8 (minor inconsistencies)

Issue Categories

1. Unexplained jargon (1 command) — third-party library name used without context
2. Misleading argument names (1 command) — argument called pattern but only supports prefix matching
3. Inconsistent example comments (2 commands) — comments don't match what flags actually do
4. Redundant text (3 commands) — duplicated information in help output
5. Docs vs CLI mismatch (1 area) — Common Tasks section differs between CLI and docs
6. Minor wording/formatting (3 commands) — placeholder formatting, flag description inconsistency

Inspection Details

• Total Commands Inspected: 40
• Commands with Issues: 10
• Date: 2026-04-13
• Method: Executed all CLI commands with --help flags and analyzed actual output against each other and against docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• Flag abbreviations (all -j, -r, -e, -v, -h flags are consistent)
• --json availability on analysis/execution commands
• --repo availability on remote-operation commands
• --repeat description consistency between run and trial
• --artifacts valid-sets list consistency between audit and logs
• Global flags (--banner, -v, -h) present on all commands
• Short command descriptions (no trailing periods, imperative verb form, consistent throughout)

⚠️ Issues found: see Detailed Findings below

Detailed Findings

---

1. Unexplained drain3 reference in gh aw logs

Command Affected: gh aw logs
Priority: Medium
Type: Unexplained jargon

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

      --train                 Train drain3 log template weights from downloaded runs and write drain3_weights.json to the output directory
```

**Issue**: `drain3` is a third-party log clustering library. Users who are not familiar with it will have no idea what "drain3 log template weights" means or what the flag does at a high level. No context is given.

**Suggested Fix**: Expand the description to explain the purpose:
```
      --train     Train log clustering template weights (drain3) from downloaded runs and save to drain3_weights.json in the output directory
```

---

#### 2. `gh aw remove [pattern]` argument name is misleading

**Command Affected**: `gh aw remove`
**Priority**: Medium
**Type**: Misleading argument name

**Current Output** (from `./gh-aw remove --help`):
```
Usage:
  gh aw remove [pattern] [flags]

...

You can provide a workflow-id prefix to remove multiple workflows, or a specific workflow-id.

Examples:
  gh aw remove my-workflow              # Remove specific workflow
  gh aw remove test-                    # Remove all workflows starting with 'test-'
```

**Issue**: The `Usage:` line uses `[pattern]` as the argument name, which implies glob/regex pattern support (e.g., `test-*`, `*.md`). However, the description clarifies it only supports **prefix** matching (e.g., `test-` removes all workflows starting with that string). A user trying `test-*` or `*-doctor` would be confused.

**Suggested Fix**: Rename the argument in Usage to `[workflow-prefix]` to match the description:
```
Usage:
  gh aw remove [workflow-prefix] [flags]
```

---

#### 3. Inconsistent example comments in `gh aw logs`

**Command Affected**: `gh aw logs`
**Priority**: Medium
**Type**: Inconsistent example comments

**Current Output** (from `./gh-aw logs --help`):
```
  gh aw logs --start-date -1w          # Download all runs after date
  gh aw logs --start-date -1w -c 5     # Download all runs from last week, show up to 5
```

**Issue**: 
- First example comment says "after date" (generic, vague) for `-1w` which is clearly "last week"
- Second example says "show up to 5" but `-c` **downloads** up to 5, not just shows them

**Suggested Fix**:
```
  gh aw logs --start-date -1w          # Download all runs from last week
  gh aw logs --start-date -1w -c 5     # Download up to 5 runs from last week
```

---

#### 4. `gh aw run` — workflow_dispatch requirement stated twice

**Command Affected**: `gh aw run`
**Priority**: Low
**Type**: Redundant text

**Current Output** (from `./gh-aw run --help`):
```
Run one or more agentic workflows on GitHub Actions using the workflow_dispatch trigger.

...

This command only works with workflows that have workflow_dispatch triggers.
```

**Issue**: The first sentence already mentions `workflow_dispatch`. The body then repeats this requirement. One of these mentions is redundant.

**Suggested Fix**: Remove the redundant body sentence, or merge:
```
Run one or more agentic workflows on GitHub Actions using the workflow_dispatch trigger.
Workflows must have a workflow_dispatch trigger to be dispatched this way.
```

---

#### 5. `gh aw mcp inspect --check-secrets` description is redundant

**Command Affected**: `gh aw mcp inspect`
**Priority**: Low
**Type**: Redundant word

**Current Output** (from `./gh-aw mcp inspect --help`):
```
      --check-secrets   Check GitHub Actions repository secrets for missing secrets
```

**Issue**: "secrets" appears twice in the same phrase — "repository **secrets** for missing **secrets**".

**Suggested Fix**:
```
      --check-secrets   Check GitHub Actions secrets are present and configured
```

---

#### 6. `gh aw trial --host-repo` placeholder not code-formatted

**Command Affected**: `gh aw trial`
**Priority**: Low
**Type**: Formatting inconsistency

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

**Issue**: `<username>` is a placeholder used without backtick/code formatting. Elsewhere in the CLI, format examples use backtick-style (e.g., `'gh aw'`, `'owner/repo'`). The `<` and `>` angle brackets are not standard CLI placeholder notation for this codebase.

**Suggested Fix**: Use a concrete example pattern consistent with other flags:
```
      --host-repo string    Custom host repository slug (default: '<your-username>/gh-aw-trial'). Use '.' for current repository
```
Or replace `<username>` with a bracketed placeholder like `{username}` or a note like "your username".

---

#### 7. `--logical-repo` description differs between `compile` and `trial`

**Commands Affected**: `gh aw compile`, `gh aw trial`
**Priority**: Low
**Type**: Inconsistent flag descriptions

**Current Output**:

`./gh-aw compile --help`:
```
      --logical-repo string         Repository to simulate workflow execution against (for trial mode)
```

`./gh-aw trial --help`:
```
  -l, --logical-repo string             Repository to simulate workflow execution against, as if the workflow was installed there (defaults to current repository)
```

**Issue**: Same flag concept has two different descriptions. The `compile` version is brief and adds "(for trial mode)" which is redundant context. The `trial` version is more complete and informative.

**Suggested Fix**: Align both descriptions:
```
      --logical-repo string   Repository to simulate workflow execution against (defaults to current repository)
```

---

#### 8. CLI "Common Tasks" and docs "Most Common Commands" diverge

**Area Affected**: `gh aw --help` (Common Tasks section) vs `docs/src/content/docs/setup/cli.md`
**Priority**: Low
**Type**: Docs vs CLI mismatch

**CLI `gh aw --help`**:
```
Common Tasks:
  gh aw init                  # Set up a new repository
  gh aw new my-workflow       # Create your first workflow
  gh aw compile               # Compile all workflows
  gh aw run my-workflow       # Execute a workflow
  gh aw logs my-workflow      # View execution logs
  gh aw audit <run-id>        # Debug a failed run
```

**Documentation** (`docs/src/content/docs/setup/cli.md`, lines 10–21) lists these as "Most Common Commands":

| Command | Description |
|---------|-------------|
| `gh aw init` | Set up your repository for agentic workflows |
| `gh aw add-wizard` | Add workflows with interactive guided setup |
| `gh aw add` | Add workflows from other repositories (non-interactive) |
| `gh aw compile` | Convert markdown to GitHub Actions YAML |
| `gh aw list` | Quick listing of all workflows |
| `gh aw run` | Execute workflows immediately in GitHub Actions |
| `gh aw status` | Check current state of all workflows |

**Issue**: `gh aw list`, `gh aw status`, `gh aw add`, and `gh aw add-wizard` are all in the docs "Most Common Commands" table but not in the CLI `Common Tasks` block. Conversely, `gh aw logs`, `gh aw audit`, and `gh aw new` are in the CLI block but not the docs table.

**Suggested Fix**: Align the two lists. At minimum, add `gh aw status` and `gh aw list` to the CLI `Common Tasks` block since they are very commonly used.

---

#### 9. `gh aw logs -c` example comment says "show" instead of "download"

**Command Affected**: `gh aw logs`
**Priority**: Low
**Type**: Misleading comment

(Note: Also covered in Finding #3 above; listed separately for completeness.)

**Current Output**:
```
  gh aw logs --start-date -1w -c 5     # Download all runs from last week, show up to 5
```

**Issue**: "show up to 5" implies `-c 5` only affects display, but it actually limits the number of runs downloaded. Should say "download up to 5" for clarity.

---

#### 10. `gh aw mcp add` — registry URL repeated

**Command Affected**: `gh aw mcp add`
**Priority**: Low
**Type**: Minor redundancy

**Current Output** (from `./gh-aw mcp add --help`):
```
Registry URL defaults to: https://api.mcp.github.com/v0.1

...

      --registry string    MCP registry URL (default: https://api.mcp.github.com/v0.1)
```

**Issue**: The registry URL `https://api.mcp.github.com/v0.1` appears both in the long description body and in the flag description. This is minor duplication.

**Suggested Fix**: Remove the explicit URL from the body text (the flag already documents the default):
```
Registry URL can be overridden with the --registry flag.
```

---

#### 11. `gh aw fix` uses "dry-run" terminology without a `--dry-run` flag

**Command Affected**: `gh aw fix`
**Priority**: Low
**Type**: Inconsistent terminology

**Current Output** (from `./gh-aw fix --help`):
```
Without --write (dry-run mode), no files are modified.

Examples:
  gh aw fix                     # Check all workflows (dry-run)
  gh aw fix --write             # Fix all workflows
```

**Issue**: The term "dry-run" is used twice (in the description and in the example comment), but there is no `--dry-run` flag. The actual flag is `--write`. Standard CLI conventions use `--dry-run` to preview; this command inverts that with `--write` to commit. The "dry-run" terminology is informally borrowed, which could confuse users expecting a `--dry-run` flag.

**Suggested Fix**: Replace "dry-run" with more descriptive language:
```
Without --write (preview mode), no files are modified.

Examples:
  gh aw fix                     # Preview changes (no files modified)
  gh aw fix --write             # Apply fixes to all workflows

Generated by CLI Consistency Checker · ● 869.1K · ◷

• expires on Apr 15, 2026, 1:50 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 · ● 214.8K · ◷