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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0 (no broken functionality found)
• Medium: 3 (inconsistent terminology / missing context)
• Low: 4 (minor wording/alignment issues)

Issue Categories

1. Terminology mismatch between Short and Long descriptions (1 command): compile
2. Flag description missing format hint (1 flag): run --ref
3. Command structure inconsistency (1 command): project
4. Minor wording/alignment inconsistencies (3 items): status, audit diff, logs

Inspection Details

• Total Commands Inspected: 30+ (all main commands and subcommands via --help)
• Commands with Issues: 5
• Date: 2026-04-14
• Method: Built binary with make build, then executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• --repo flag — consistent description across all 10+ commands that use it
• --engine flag — consistently described across all commands
• --json / -j flag — consistently described
• --dir / -d flag — consistently described across relevant commands
• disable / enable — symmetric and consistent
• audit diff — well documented
• logs date filtering — clear and comprehensive examples
• trial repository modes — clearly explained

⚠️ Issues found:

• compile Long description uses "YAML workflows" vs Short uses "GitHub Actions YAML"
• run --ref flag missing format hint present in equivalent status and logs flags
• project parent command lacks "Available subcommands:" section used by pr, secrets, mcp
• status example alignment off for --json line
• audit diff --format and logs --format value ordering differs
• logs --filtered-integrity wording slightly different between flag and example

Detailed Findings

1. compile Long description uses imprecise "YAML workflows" instead of "GitHub Actions YAML"

Commands Affected: compile
Priority: Medium
Type: Terminology inconsistency between Short and Long descriptions

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

compile          Compile agentic workflow Markdown files into GitHub Actions YAML
```

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

**Issue**: The Long description (shown as the first line of `compile --help`) says "to YAML workflows" while the Short description (shown in the root `--help` table) says "into GitHub Actions YAML". "YAML workflows" is technically imprecise — it could refer to any YAML, whereas "GitHub Actions YAML" is both accurate and consistent with the root help.

**Suggested Fix**: Update the Long description to open with: `Compile one or more agentic workflow Markdown files into GitHub Actions YAML.`

---

#### 2. `run --ref` flag missing format hint

**Commands Affected**: `run`
**Priority**: Medium
**Type**: Inconsistent flag description

**Current Output** (from `./gh-aw run --help`):
```
--ref string              Branch or tag name to run the workflow on (default: current branch)
```

**Equivalent flags in other commands** (from `./gh-aw status --help` and `./gh-aw logs --help`):
```
--ref string     Filter runs by branch or tag name (e.g., main, v1.0.0)
```

**Issue**: The `run --ref` flag description does not include the format hint `(e.g., main, v1.0.0)` that `status --ref` and `logs --ref` both provide. New users benefit from the example, which is already present on semantically equivalent flags.

**Suggested Fix**: Update `run --ref` description to: `Branch or tag name to run the workflow on (e.g., main, v1.0.0) (default: current branch)`

---

#### 3. `project` command missing "Available subcommands:" introductory block

**Commands Affected**: `project`
**Priority**: Medium
**Type**: Structural inconsistency

**Current Output** (from `./gh-aw project --help`):
```
Manage GitHub Projects V2 boards linked to repositories.

GitHub Projects V2 provides kanban-style project boards for tracking issues,
pull requests, and tasks across repositories.

This command allows you to create new projects owned by users or organizations
and optionally link them to specific repositories.

Examples:
  ...

Usage:
  gh aw project [command]

Available Commands:
  new Create a new GitHub Project V2
```

**Other parent commands** (from `./gh-aw pr --help`, `./gh-aw secrets --help`, `./gh-aw mcp --help`):
```
Available subcommands:
  • transfer - Transfer a pull request to another repository
```
(before the Usage section, as an introductory list)

**Issue**: The `project` command's Long description skips the bullet-list "Available subcommands:" section that `pr`, `secrets`, and `mcp` all include. The subcommands are only visible in the cobra-generated `Available Commands:` section at the bottom. This is inconsistent with the pattern used by sibling parent commands.

**Suggested Fix**: Add an "Available subcommands:" bullet-list block to `project`'s Long description, for example:
```
Available subcommands:
  • new - Create a new GitHub Project V2
```

---

#### 4. `status` example has misaligned comment on `--json` line

**Commands Affected**: `status`
**Priority**: Low
**Type**: Formatting/alignment

**Current Output** (from `./gh-aw status --help`):
```
Examples:
  gh aw status                          # Show all workflow status
  gh aw status ci-                      # Show workflows with 'ci-' in name
  gh aw status --json                    # Output in JSON format
  gh aw status --ref main                # Show latest run status for main branch
```

**Issue**: The `--json` example line has one extra leading space before the `#` comment (`                   ` instead of `                  `), causing it to be misaligned with the surrounding examples.

**Suggested Fix**: Remove the extra space so `--json` comment aligns consistently with the others.

---

#### 5. `audit diff --format` and `logs --format` list values in different order

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

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

**Current Output** (from `./gh-aw logs --help`):
```
--format string         Output format for cross-run audit report: markdown, pretty
```

**Issue**: The `--format` flag in `audit diff` lists options as `pretty, markdown` while `logs` lists them as `markdown, pretty`. Users referencing one command's help while using the other may find the inconsistency confusing.

**Suggested Fix**: Standardize both to `markdown, pretty` (or alphabetical order consistently).

---

#### 6. `logs --filtered-integrity` wording differs between flag description and example comment

**Commands Affected**: `logs`
**Priority**: Low
**Type**: Minor wording inconsistency

**Current flag description** (from `./gh-aw logs --help`):
```
--filtered-integrity    Filter to runs with DIFC (data integrity flow control) integrity-filtered items in the gateway logs
```

**Current example comment** (same help output):
```
gh aw logs --filtered-integrity      # Filter logs with DIFC (data integrity flow control) integrity-filtered items in gateway logs
```

**Issue**: Flag description says "in the gateway logs" (with "the") while the example comment omits "the" ("in gateway logs"). Minor grammatical inconsistency.

**Suggested Fix**: Use consistent wording; either "in the gateway logs" in both, or "in gateway logs" in both.

---

#### 7. `version` Short and Long descriptions differ in wording

**Commands Affected**: `version`
**Priority**: Low
**Type**: Description mismatch

**Short description** (from `./gh-aw --help` command table):
```
version          Show gh aw extension version information
```

**Long description** (from `./gh-aw version --help`):
```
Show the installed version of the gh aw extension.

Issue: "Show gh aw extension version information" vs "Show the installed version of the gh aw extension." Both convey the same meaning but use different phrasing. Minor but slightly inconsistent for users switching between root help and command help.

Suggested Fix: Align one to the other, e.g., update the Long description to: Show version information for the installed gh aw extension.

Generated by CLI Consistency Checker · ● 1.4M · ◷

• expires on Apr 16, 2026, 1:50 PM UTC