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

[github-actions]

Summary

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

Breakdown by Severity

• High: 0
• Medium: 1 (incorrect/irrelevant content)
• Low: 3 (minor inconsistencies)

Inspection Details

• Total Commands Inspected: 37 (including all subcommands)
• Commands with Issues: 4
• Date: 2026-04-24
• Method: Executed all CLI commands and subcommands with --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• Flag naming consistency across commands (e.g., -e/--engine, -r/--repo, -j/--json, -d/--dir)
• Global flags consistency (--banner, -v/--verbose, -h/--help)
• Engine option values (copilot, claude, codex, gemini, crush) — consistently listed
• Workflow ID format documentation — consistently described across all commands
• Examples presence — all commands have meaningful examples
• Technical accuracy of flag descriptions

⚠️ Issues found:

• secrets bootstrap: irrelevant documentation link
• trial: inconsistent comment alignment in examples
• logs: unclear acronym in flag description
• validate equivalence description: minor formatting

Detailed Findings

1. secrets bootstrap — Irrelevant Documentation Link

Command Affected: gh aw secrets bootstrap
Priority: Medium
Type: Incorrect documentation / copy-paste error

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

Documentation:
  https://cli.github.com/manual/gh_auth_login
Examples:
  gh aw secrets bootstrap                        # Check and set up all required secrets
  gh aw secrets bootstrap --non-interactive      # Display missing secrets without prompting
  gh aw secrets bootstrap --engine copilot       # Check secrets for a specific engine

Issue: The Documentation: link points to https://cli.github.com/manual/gh_auth_login — the gh auth login reference page — which is entirely unrelated to the secrets bootstrap command. This is likely a copy-paste artifact.

Suggested Fix: Remove the Documentation: section entirely, or replace it with a link relevant to managing GitHub Actions secrets (e.g., GitHub docs for repository secrets).

---

2. trial — Inconsistent Comment Alignment in Examples

Command Affected: gh aw trial
Priority: Low
Type: Formatting inconsistency

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

  gh aw trial githubnext/agentics/my-workflow --host-repo myorg/myrepo         # Use myorg/myrepo as host for trial execution
  gh aw trial githubnext/agentics/my-workflow --logical-repo myorg/myrepo  # Simulate running against myorg/myrepo
  gh aw trial githubnext/agentics/my-workflow --clone-repo myorg/myrepo   # Clone myorg/myrepo contents into host

Issue: The # comment markers are misaligned — the first line has 9 extra spaces before #, while the other two lines have 2–3 spaces. This creates visual inconsistency in the examples block.

Suggested Fix: Align the # comment markers consistently across all three lines, or remove the alignment attempt and use a single space before each #.

---

3. logs --filtered-integrity — Obscure Acronym Without Context

Command Affected: gh aw logs
Priority: Low
Type: Unclear documentation

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

  --filtered-integrity    Filter to runs with DIFC (data integrity flow control) integrity-filtered items in the gateway logs

Issue: DIFC is not a standard industry acronym and is redundantly expanded as "data integrity flow control" while the flag name itself says "filtered-integrity". The phrase "DIFC (data integrity flow control) integrity-filtered items" is tautological. Users unfamiliar with the internal system won't understand what this flag does from the description.

Suggested Fix: Simplify the description to something like: Filter to runs where the gateway filtered items due to integrity checks.

---

4. validate — Equivalence Description References Hidden Flags

Command Affected: gh aw validate
Priority: Low
Type: Documentation clarity

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

Validate one or more agentic workflows by compiling and running all linters without
generating lock files. This is equivalent to:

  gh aw compile --validate --no-emit --zizmor --actionlint --poutine

Issue: The flags --validate and --zizmor are present in compile but do not appear in the default compile --help output (they are rendered lower in the flags list along with many others). Users following the "equivalent command" snippet and trying to discover what --validate or --zizmor do in compile will have to scroll through a long flag list. The equivalence is technically accurate but may mislead users into thinking these flags are missing from compile.

Suggested Fix: No code change required, but optionally add a note such as: (Note: --validate and --zizmor are compile flags; run gh aw compile --help to see all available flags.)

Generated by CLI Consistency Checker · ● 1M · ◷

• expires on Apr 26, 2026, 1:46 PM UTC