[cli-consistency] CLI Consistency Issues and Missing Flags

[github-actions]

Summary

Automated CLI consistency inspection of gh-aw identified 4 real issues affecting command completeness and consistency. All commands execute successfully, but some lack flags that are available in similar commands.

Inspection Summary

• Total Commands Inspected: 32 (main commands, subcommands, and utility commands)
• Commands with Issues: 4
• Date: 2025-03-09
• Method: Executed all CLI commands with --help flags and compared outputs

Findings by Severity

High Priority (3):

• run command missing --json flag
• audit command missing --repo flag
• new command missing --engine flag

Medium Priority (1):

• list command missing --dir flag (uses --path instead)

---

Detailed Findings

Issue 1: run command missing --json flag (HIGH)

Command: gh aw run

Current Behavior:

./gh-aw run --help
# Shows flags: --auto-merge-prs, --dry-run, --enable-if-needed, -e/--engine, -h/--help, --push, -F/--raw-field, --ref, --repeat, -r/--repo
# MISSING: -j/--json

Expected Behavior: Should support --json flag like other output/list commands:

• gh aw list --json ✓ works
• gh aw status --json ✓ works
• gh aw audit --json ✓ works
• gh aw run --json ✗ MISSING

Impact: Users cannot get machine-readable JSON output from the run command, unlike similar commands like audit, status, and list.

Suggested Fix: Add --json flag to run command for consistency with other output-producing commands.

Issue 2: audit command missing --repo flag (HIGH)

Command: gh aw audit (run-id)

Current Behavior:

./gh-aw audit --help
# Shows flags: -h/--help
# Does NOT show: -r/--repo

Expected Behavior: Should support --repo flag like other commands:

• gh aw list --repo owner/repo ✓ works
• gh aw status --repo owner/repo ✓ works
• gh aw logs --repo owner/repo ✓ works
• gh aw run --repo owner/repo ✓ works
• gh aw audit (run-id) --repo owner/repo ✗ MISSING

Impact: Cannot audit workflow runs from other repositories. Users must change their working directory or clone the target repository to audit workflows.

Suggested Fix: Add --repo flag to audit command for consistency with other repository-aware commands.

Issue 3: new command missing --engine flag (HIGH)

Command: gh aw new (workflow-name)

Current Behavior:

./gh-aw new --help
# Shows no --engine flag

Expected Behavior: Should support --engine flag like related commands:

• gh aw add --engine copilot ✓ works
• gh aw compile --engine claude ✓ works
• gh aw new --engine copilot ✗ MISSING

Impact: Cannot create workflow templates tailored to specific AI engines. Users must edit the generated file after creation to specify the engine, adding an extra step.

Suggested Fix: Add --engine flag to new command to match add and compile.

Issue 4: list command uses --path instead of --dir (MEDIUM)

Command: gh aw list

Current Behavior:

./gh-aw list --help
# Shows: --path string (instead of --dir)

Inconsistency:

• gh aw compile --dir custom/ ✓ uses --dir
• gh aw validate --dir custom/ ✓ uses --dir
• gh aw list --path custom/ uses --path (different!)

Impact: Users need to remember different flag names for similar functionality. The example in list help text shows --path workflows which is confusing when other commands use --dir.

Suggested Fix: Either:

1. Add --dir as an alias for --path in list command
2. Or standardize all commands to use the same flag name consistently

Note: This is less critical since --path works and is documented, but consistency matters for user experience.

---

Positive Findings ✅

• ✓ All commands execute without errors
• ✓ All commands have clear, descriptive first-line descriptions
• ✓ All commands have proper Usage sections
• ✓ Examples are consistently present across commands
• ✓ Help text formatting is clean and readable
• ✓ Subcommands are properly documented (mcp, pr subcommands work well)
• ✓ Global flags (--verbose, --help) are consistently available
• ✓ Majority of flags are consistent across similar commands

---

Recommendations

1. Priority 1: Add missing flags to run, audit, and new commands
2. Priority 2: Standardize --dir vs --path naming across all commands
3. Priority 3: Consider adding integration tests to catch these types of inconsistencies in the future

Generated by CLI Consistency Checker · ◷

• expires on Mar 11, 2026, 1:39 PM UTC