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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0 (No functionality-breaking issues found)
• Medium: 2 (Misleading behavior descriptions)
• Low: 5 (Incomplete documentation of flags)

Issue Categories

1. Misleading --repeat flag documentation (1 command)

   • The run docs describe --repeat 3 as "# Repeat 3 times" but the CLI itself says "Run 4 times total (1 initial + 3 repeats)"

2. Incomplete options lists in documentation (5 commands)

   • compile, logs, remove, fix, and validate docs are missing several CLI flags from their options lists

Inspection Details

• Total Commands Inspected: 27 (--help run on all commands and subcommands)
• Commands with Issues: 6
• Date: 2026-04-21
• Method: Executed all CLI commands with --help flags and compared with docs/src/content/docs/setup/cli.md

Findings Summary

✅ No issues found in these areas:

• All commands build and execute correctly
• Engine flag (--engine) values consistent across all commands: copilot, claude, codex, gemini, crush
• Global flags (--banner, -v/--verbose, -h/--help) consistent across all commands
• --repo/-r flag consistent across all commands that support it
• --json/-j flag consistent across all commands that support it
• Command descriptions clear and unambiguous
• No spelling or grammar errors found in CLI help text
• audit diff subcommand correctly documented and functional
• mcp subcommands (add, inspect, list, list-tools) consistent and well-documented
• pr transfer subcommand consistent and well-documented
• All commands in the main help index are real, functional commands

⚠️ Issues found:

• run docs use ambiguous comment for --repeat example
• compile, logs, remove, fix, validate docs have incomplete options lists

Detailed Findings

1. run docs: --repeat comment is misleading

Commands Affected: gh aw run
Priority: Medium
Type: Inconsistency between CLI help and documentation

CLI help output (from ./gh-aw run --help):

gh aw run daily-perf-improver --repeat 3  # Run 4 times total (1 initial + 3 repeats)

Documentation (docs/src/content/docs/setup/cli.md, line 323):

gh aw run workflow --repeat 3               # Repeat 3 times

Issue: The CLI itself is explicit that --repeat 3 results in 4 total runs (1 initial + 3 repeats), but the docs comment "# Repeat 3 times" implies only 3 total runs. This can mislead users into thinking they're getting 3 runs when they get 4.

Suggested Fix: Change the docs comment to:

gh aw run workflow --repeat 3               # Run 4 times total (1 initial + 3 repeats)

---

2. compile docs options list is significantly incomplete

Commands Affected: gh aw compile
Priority: Medium
Type: Missing documentation

CLI flags present (from ./gh-aw compile --help) not listed in docs options:

--action-mode string          Action script inlining mode (inline, dev, release)
--action-tag string           Override action SHA or tag for actions/setup
--actionlint                  Run actionlint linter on generated .lock.yml files
--actions-repo string         Override the external actions repository
--allow-action-refs           Allow unresolved action refs and emit warnings
--fail-fast                   Stop at the first validation error
--force-refresh-action-pins   Force refresh of action pins
--logical-repo string         Repository to simulate workflow execution against
--no-check-update             Skip checking for gh-aw updates
--poutine                     Run poutine security scanner
--refresh-stop-time           Force regeneration of stop-after times
--runner-guard                Run runner-guard taint analysis scanner
--schedule-seed string        Override the repository slug used for schedule scattering
--trial                       Enable trial mode compilation
--validate-images             Require Docker for container image validation

Documentation (docs/src/content/docs/setup/cli.md), current options list:

--validate, --strict, --fix, --zizmor, --dependabot, --json, --no-emit, --watch, --purge, --stats, --approve

Issue: Many useful flags are completely absent from the docs, including commonly-used ones like --fail-fast, --trial, --logical-repo, and --validate-images.

Suggested Fix: Expand the Options list for compile to include at minimum the most user-facing flags: --fail-fast, --no-check-update, --trial, --logical-repo, --validate-images, --allow-action-refs, --actionlint, --poutine.

---

3. logs docs missing --format and --summary-file from options list

Commands Affected: gh aw logs
Priority: Low
Type: Missing documentation

CLI flags present (from ./gh-aw logs --help) not in the options list:

--format string         Output format for cross-run audit report: pretty, markdown
--summary-file string   Path to write the summary JSON file (default "summary.json")

Issue: --format is mentioned in the body text but absent from the formal Options list. --summary-file is not mentioned at all in the docs. Users who rely on the options list will miss these.

Suggested Fix: Add --format and --summary-file to the logs Options list in the docs.

---

4. remove docs missing --dir flag from options

Commands Affected: gh aw remove
Priority: Low
Type: Missing documentation

CLI flag present (from ./gh-aw remove --help):

-d, --dir string     Workflow directory (default: .github/workflows)

Documentation current options: --keep-orphans (only)

Issue: The --dir flag is present in the CLI but not documented.

Suggested Fix: Update the Options list to: --keep-orphans, --dir/-d

---

5. fix docs missing --dir flag from options

Commands Affected: gh aw fix
Priority: Low
Type: Missing documentation

CLI flag present (from ./gh-aw fix --help):

-d, --dir string      Workflow directory (default: .github/workflows)

Documentation current options: --write, --list-codemods

Issue: The --dir flag is present in the CLI but not documented.

Suggested Fix: Update Options to include --dir/-d.

---

6. validate docs missing --allow-action-refs and --validate-images flags

Commands Affected: gh aw validate
Priority: Low
Type: Missing documentation

CLI flags present (from ./gh-aw validate --help) not in docs:

--allow-action-refs   Allow unresolved action refs and emit warnings instead of failing validation
--validate-images     Require Docker to be available for container image validation

Documentation current options: --engine/-e, --dir/-d, --strict, --json/-j, --fail-fast, --stats, --no-check-update

Suggested Fix: Add --allow-action-refs and --validate-images to the validate Options list.

---

7. logs CLI help missing --format and --summary-file examples in the examples block

Commands Affected: gh aw logs
Priority: Low
Type: Missing documentation

Current CLI examples for format (from ./gh-aw logs --help):

gh aw logs --format markdown         # Generate cross-run security audit report in Markdown
gh aw logs --format pretty           # Generate cross-run security audit report in console format

These examples exist in the CLI help but the --summary-file flag has no example.

Suggested Fix: Add an example for --summary-file to the CLI help, e.g.:

gh aw logs --summary-file ""          # Disable writing summary.json
gh aw logs --summary-file my-summary.json  # Custom summary file path

Generated by CLI Consistency Checker · ● 808.4K · ◷

• expires on Apr 23, 2026, 1:51 PM UTC