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

[github-actions]

Summary

Automated CLI consistency inspection found 10 inconsistencies across command help text that should be addressed for a better user experience.

Breakdown by Severity

• High: 0 (Breaks functionality)
• Medium: 6 (Inconsistent/misleading descriptions)
• Low: 4 (Minor inconsistencies)

Issue Categories

1. Short vs Long description mismatches (4 commands) — audit, remove, add-wizard, update
2. Asymmetric sibling command descriptions (1 pair) — enable/disable
3. Overly vague short descriptions (1 command) — secrets
4. Documentation out of sync with CLI (1 command) — mcp-server
5. Flag inconsistency (1 command) — trial --repo
6. Minor wording issues (2 commands) — compile, hash-frontmatter

Inspection Details

• Total Commands Inspected: 28 (all top-level + subcommands)
• Commands with Issues: 9
• Date: 2026-03-17
• Method: Executed all CLI commands with --help flags, compared actual output to docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• Flag names and short-flags (-h, -v, -r, -j, -e, -d, -f, -w, -F) are consistent across commands
• All commands have at least 3 examples
• All commands include --help and global flags
• Typos/spelling: none found
• Example paths and commands appear correct
• MCP subcommands (add, inspect, list, list-tools) are internally consistent
• secrets, project, completion, pr subcommand groups are consistent

⚠️ Issues found:

• Short/Long description mismatches (audit, remove, add-wizard, update)
• Asymmetric sibling descriptions (enable vs disable)
• Vague short description (secrets)
• Documentation missing a tool (mcp-server / docs/setup/cli.md)
• Flag semantic inconsistency (trial --repo)

Detailed Findings

1. audit — "Investigate" vs "Audit" terminology mismatch

Command Affected: audit
Priority: Medium
Type: Inconsistent terminology between short and long description

Current Output (from gh aw --help):

audit       Investigate an agentic workflow run and generate a detailed report
```

**Current Output** (from `gh aw audit --help`):
```
Audit a single workflow run by downloading artifacts and logs, detecting errors,
analyzing MCP tool usage, and generating a concise Markdown report suitable for AI agents.
```

**Issue**: The short description says "Investigate" while the long description says "Audit" — and the command is named `audit`. The word "Investigate" is also the short description for the `audit` sub-section in the docs.

**Suggested Fix**: Align short description with the command name: `"Audit an agentic workflow run and generate a detailed report"`

---

#### 2. `remove` — "name prefix" vs "workflow-id pattern" mismatch

**Command Affected**: `remove`
**Priority**: Medium
**Type**: Misleading inconsistency between short and long descriptions

**Current Output** (from `gh aw --help`):
```
remove      Remove agentic workflow files matching the given name prefix
```

**Current Output** (from `gh aw remove --help`):
```
Remove agentic workflow files matching the given workflow-id pattern.
...
You can provide a workflow-id prefix to remove multiple workflows, or a specific workflow-id.
```

**Issue**: The short description says "name prefix" implying only prefix matching, while the long description correctly says "workflow-id pattern" (which supports both prefix and exact match). "name" is also less precise than "workflow-id".

**Suggested Fix**: Change short description to: `"Remove agentic workflow files matching the given workflow-id pattern"`

---

#### 3. `add-wizard` — missing "agentic" in long description

**Command Affected**: `add-wizard`
**Priority**: Medium
**Type**: Inconsistency between short description and long description

**Current Output** (from `gh aw --help`):
```
add-wizard  Interactively add one or more agentic workflows with guided setup
```

**Current Output** (from `gh aw add-wizard --help`):
```
Interactively add one or more workflows with guided setup.
```

**Issue**: The short description (shown in parent listing) includes "agentic" but the long description (shown in `add-wizard --help`) omits it. All similar commands use "agentic workflows" consistently.

**Suggested Fix**: Change long description first line to: `"Interactively add one or more agentic workflows with guided setup."`

---

#### 4. `enable`/`disable` — asymmetric short descriptions

**Commands Affected**: `enable`, `disable`
**Priority**: Medium
**Type**: Inconsistent sibling command descriptions

**Current Output** (from `gh aw --help`):
```
disable     Disable agentic workflows and cancel any in-progress runs
enable      Enable agentic workflows
```

**Issue**: The `disable` short description helpfully notes it cancels in-progress runs, but `enable` has a much shorter description. These are sibling commands and their descriptions should follow the same pattern. The important "cancel any in-progress runs" detail is buried only in disable's description (and not mentioned in `enable --help` at all), which could mislead users about the full impact of `disable`.

**Suggested Fix**: Make `enable` more descriptive: `"Enable agentic workflows, or all workflows if no IDs are provided"`. Alternatively, simplify `disable` to match: `"Disable agentic workflows and cancel any in-progress runs"` → keep as-is but update `enable` to `"Enable agentic workflows by ID, or all workflows if no IDs are provided"`.

---

#### 5. `secrets` — overly vague short description

**Command Affected**: `secrets`
**Priority**: Medium
**Type**: Short description loses important context vs long description

**Current Output** (from `gh aw --help`):
```
secrets     Manage repository secrets
```

**Current Output** (from `gh aw secrets --help`):
```
Manage GitHub Actions secrets for GitHub Agentic Workflows.
```

**Issue**: The short description "Manage repository secrets" is generic and could apply to any tool. The long description correctly scopes it to "GitHub Actions secrets for GitHub Agentic Workflows". The short description should include enough context so users understand what kind of secrets are being managed.

**Suggested Fix**: Change short description to: `"Manage GitHub Actions secrets for agentic workflows"`

---

#### 6. `mcp-server` documentation missing `fix` tool

**Command Affected**: `mcp-server`
**Priority**: Medium
**Type**: Documentation out of sync with CLI help

**Current CLI Output** (from `gh aw mcp-server --help`):
```
The server provides the following tools:
  - status      - Show status of agentic workflow files
  - compile     - Compile Markdown workflows to GitHub Actions YAML
  - logs        - Download and analyze workflow logs (requires write+ access)
  - audit       - Investigate a workflow run, job, or step and generate a report (requires write+ access)
  - mcp-inspect - Inspect MCP servers in workflows and list available tools
  - add         - Add workflows from remote repositories to .github/workflows
  - update      - Update workflows from their source repositories
  - fix         - Apply automatic codemod-style fixes to workflow files
```

**Current Documentation** (`docs/src/content/docs/setup/cli.md`):
```
**Available Tools:** status, compile, logs, audit, mcp-inspect, add, update
```

**Issue**: The `fix` tool is present in the CLI's `mcp-server` help but missing from the documentation. Users consulting docs would not know `fix` is available via MCP.

**Suggested Fix**: Add `fix` to the docs: `**Available Tools:** status, compile, logs, audit, mcp-inspect, add, update, fix`

---

#### 7. `trial --repo` — semantic inconsistency with other commands

**Command Affected**: `trial`
**Priority**: Low
**Type**: Flag semantic inconsistency

**Current Output** (from `gh aw trial --help`):
```
--repo string   Alias for --host-repo
```

**Comparison** (all other commands with `--repo`):
```
-r, --repo string   Target repository ([HOST/]owner/repo format). Defaults to current repository
```

**Issue**: In every other command (`run`, `logs`, `audit`, `status`, etc.), `--repo` means "target repository" and has `-r` as shorthand. In `trial`, `--repo` is an alias for `--host-repo` (the trial execution host), which is a different concept. There is no `-r` shorthand. This could confuse users who expect `--repo` to mean "the repository context" (which in `trial` is `--logical-repo`).

**Suggested Fix**: Consider documenting the semantic difference more prominently, or adding `-r` shorthand to be consistent with other commands.

---

#### 8. `update` long description missing "agentic"

**Command Affected**: `update`
**Priority**: Low
**Type**: Minor wording inconsistency

**Current Output** (from `gh aw --help`):
```
update      Update agentic workflows from their source repositories
```

**Current Output** (from `gh aw update --help` first line):
```
Update one or more workflows from their source repositories.
```

**Issue**: Short description (parent listing) includes "agentic" but the long description omits it. Minor inconsistency, as other commands (`add-wizard`, `add`, `compile`, etc.) consistently use "agentic workflows".

**Suggested Fix**: Update long description first line to: `"Update one or more agentic workflows from their source repositories."`

---

#### 9. `compile` long description — "YAML workflows" wording

**Command Affected**: `compile`
**Priority**: Low
**Type**: Minor wording imprecision

**Current Output** (from `gh aw compile --help`):
```
Compile one or more agentic workflows to YAML workflows.
```

**Short description** (from `gh aw --help`):
```
compile     Compile agentic workflow files (.md) into GitHub Actions workflows (.lock.yml)
```

**Issue**: The long description says "to YAML workflows" which is somewhat redundant (agentic workflows compiled to "workflows"?). The short description is much more precise: `.md` → GitHub Actions workflows (`.lock.yml`). The long description should better explain the output.

**Suggested Fix**: `"Compile one or more agentic workflow files (.md) into GitHub Actions YAML (.lock.yml)."`

---

#### 10. `hash-frontmatter` short description lacks precision

**Command Affected**: `hash-frontmatter`
**Priority**: Low
**Type**: Short description is less precise than long description

**Current Output** (from `gh aw --help`):
```
hash-frontmatter Compute frontmatter hash for a workflow
```

**Current Output** (from `gh aw hash-frontmatter --help`):
```
Compute a deterministic SHA-256 hash of workflow frontmatter.

Issue: The short description says "frontmatter hash" without specifying the algorithm, but the long description specifies "SHA-256 hash". The short description could be slightly more informative.

Suggested Fix: "Compute a SHA-256 hash of workflow frontmatter" (brief but precise)

Generated by CLI Consistency Checker · ◷

• expires on Mar 19, 2026, 1:43 PM UTC