[cli-consistency] CLI Consistency Issues - 2026-05-11

[github-actions]

Summary

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

Breakdown by Severity

• High: 1 (Contradictory description)
• Medium: 1 (Non-standard format)
• Low: 1 (Missing docs option)

Inspection Details

• Total Commands Inspected: 23
• Commands with Issues: 3
• Date: 2026-05-11
• Method: Executed all CLI commands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency (-e/--engine, -r/--repo, -j/--json, etc.) is uniform across all commands
• Engine values (copilot, claude, codex, gemini, crush) are consistently documented in all --engine flags
• --repo flag format ([HOST/]owner/repo format) is consistent across all commands
• No typos or grammar errors found in any help text
• All commands have appropriate examples
• No duplicate command aliases

⚠️ Issues found:

• audit command has a high-priority contradiction between its short and long descriptions
• trial command uses a non-standard examples format compared to all other commands
• update docs options list is missing the --cool-down flag

Detailed Findings

1. audit — Contradictory "detailed" vs "concise" in descriptions

Command Affected: gh aw audit
Priority: High
Type: Contradictory description

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

Short description (shown in parent gh aw --help):

audit            Audit a workflow run and generate a detailed report

Long description (shown in gh aw audit --help):

Audit one or more workflow runs by downloading artifacts and logs, detecting errors,
analyzing MCP tool usage, and generating a concise report suitable for AI agents.

Issue: The short description says "detailed report" while the long description says "concise report". These are contradictory — the report cannot be both detailed and concise simultaneously.

Source: pkg/cli/audit.go lines 31–33:

Short: "Audit a workflow run and generate a detailed report",
Long: `Audit one or more workflow runs by downloading artifacts and logs, detecting errors,
analyzing MCP tool usage, and generating a concise report suitable for AI agents.

Suggested Fix: Align the descriptions. Since the long description says "concise report suitable for AI agents", update the short description to match:

Short: "Audit a workflow run and generate a concise report",

Or conversely, if "detailed" is more accurate, update the long description to say "detailed report".

---

2. trial — Non-standard examples format

Command Affected: gh aw trial
Priority: Medium
Type: Format inconsistency

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

Single workflow:
  gh aw trial githubnext/agentics/weekly-research
  Outputs: stdout + local trials/weekly-research.DATETIME-ID.json + trial repo trials/

Multiple workflows (for comparison):
  gh aw trial githubnext/agentics/daily-plan githubnext/agentics/weekly-research
  ...

Repository mode examples:
  gh aw trial githubnext/agentics/my-workflow --host-repo myorg/myrepo
  ...

Repeat and cleanup examples:
  ...

Auto-merge examples:
  ...

Advanced examples:
  ...

Issue: The trial command embeds examples in multiple categorized inline sections within the description body. All other commands (run, compile, audit, add, status, etc.) use a single clean Examples: block with # comment style annotations. The current format mixes prose, output descriptions, and examples together, making it harder to scan.

Suggested Fix: Restructure to use the standard examples format:

Examples:
  gh aw trial githubnext/agentics/ci-doctor          # Test remote workflow
  gh aw trial ./workflow.md --logical-repo owner/repo # Simulate running against different repo
  gh aw trial ./workflow.md --host-repo owner/repo   # Use existing repo as host
  gh aw trial ./workflow.md --dry-run                # Preview without executing
  gh aw trial workflow --repeat 3                    # Run 4 times total (1 initial + 3 repeats)
  gh aw trial workflow --delete-host-repo-after      # Delete trial repo after completion
  gh aw trial workflow --auto-merge-prs              # Auto-merge PRs created during trial
  gh aw trial workflow --trigger-context https://github.com/owner/repo/issues/123  # Provide issue context

Move detailed explanations of repository modes to the description prose.

---

3. update docs — Missing --cool-down option

Command Affected: gh aw update
Priority: Low
Type: Documentation gap

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

  gh aw update --cool-down 0           # Disable cooldown and apply all pending releases immediately
  gh aw update --cool-down 3d          # Apply a custom 3-day cooldown period

Flags:
      --cool-down string       Cooldown period before applying a new release (e.g. 7d, 24h, 0 to disable).
                               Does not apply to actions/* or github/* repositories (default "7d")

Current Docs (docs/src/content/docs/setup/cli.md, line 604):

**Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`,
`--disable-release-bump`, `--create-pull-request`, `--no-compile`, `--no-redirect`

Issue: The --cool-down flag is a real, documented CLI flag with a default value of 7d, but it is missing from the docs options list for the update command. Users reading the docs won't know this flag exists.

Suggested Fix: Add --cool-down to the docs options list:

**Options:** `--cool-down`, `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile`, `--no-redirect`

Generated by CLI Consistency Checker · ● 13.2M · ◷

• expires on May 13, 2026, 2:11 PM UTC

[github-actions]

🍪 Issue Monster selected this for Copilot

I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

If assignment succeeds, 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 · ● 58.5K · ◷