Skip to content

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

Closed

Description

@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

Activity

  1. github-actions commented on May 11, 2026

    @github-actions
    ContributorAuthor

    🍪 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 · ◷

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

automationclicookieIssue Monster Loves Cookies!documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions