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 flagaudit command missing --repo flagnew 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 ✓ worksgh aw status --json ✓ worksgh aw audit --json ✓ worksgh 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 ✓ worksgh aw status --repo owner/repo ✓ worksgh aw logs --repo owner/repo ✓ worksgh aw run --repo owner/repo ✓ worksgh 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 ✓ worksgh aw compile --engine claude ✓ worksgh 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 --dirgh aw validate --dir custom/ ✓ uses --dirgh 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:
- Add
--dir as an alias for --path in list command
- 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
- Priority 1: Add missing flags to
run, audit, and new commands
- Priority 2: Standardize
--dir vs --path naming across all commands
- Priority 3: Consider adding integration tests to catch these types of inconsistencies in the future
Generated by CLI Consistency Checker · ◷
Summary
Automated CLI consistency inspection of
gh-awidentified 4 real issues affecting command completeness and consistency. All commands execute successfully, but some lack flags that are available in similar commands.Inspection Summary
--helpflags and compared outputsFindings by Severity
High Priority (3):
runcommand missing--jsonflagauditcommand missing--repoflagnewcommand missing--engineflagMedium Priority (1):
listcommand missing--dirflag (uses--pathinstead)Detailed Findings
Issue 1: run command missing --json flag (HIGH)
Command:
gh aw runCurrent Behavior:
Expected Behavior: Should support
--jsonflag like other output/list commands:gh aw list --json✓ worksgh aw status --json✓ worksgh aw audit --json✓ worksgh aw run --json✗ MISSINGImpact: Users cannot get machine-readable JSON output from the
runcommand, unlike similar commands likeaudit,status, andlist.Suggested Fix: Add
--jsonflag toruncommand for consistency with other output-producing commands.Issue 2: audit command missing --repo flag (HIGH)
Command:
gh aw audit (run-id)Current Behavior:
Expected Behavior: Should support
--repoflag like other commands:gh aw list --repo owner/repo✓ worksgh aw status --repo owner/repo✓ worksgh aw logs --repo owner/repo✓ worksgh aw run --repo owner/repo✓ worksgh aw audit (run-id) --repo owner/repo✗ MISSINGImpact: Cannot audit workflow runs from other repositories. Users must change their working directory or clone the target repository to audit workflows.
Suggested Fix: Add
--repoflag toauditcommand 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 flagExpected Behavior: Should support
--engineflag like related commands:gh aw add --engine copilot✓ worksgh aw compile --engine claude✓ worksgh aw new --engine copilot✗ MISSINGImpact: 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
--engineflag tonewcommand to matchaddandcompile.Issue 4: list command uses --path instead of --dir (MEDIUM)
Command:
gh aw listCurrent Behavior:
./gh-aw list --help # Shows: --path string (instead of --dir)Inconsistency:
gh aw compile --dir custom/✓ uses--dirgh aw validate --dir custom/✓ uses--dirgh aw list --path custom/uses--path(different!)Impact: Users need to remember different flag names for similar functionality. The example in
listhelp text shows--path workflowswhich is confusing when other commands use--dir.Suggested Fix: Either:
--diras an alias for--pathinlistcommandNote: This is less critical since
--pathworks and is documented, but consistency matters for user experience.Positive Findings ✅
mcp,prsubcommands work well)--verbose,--help) are consistently availableRecommendations
run,audit, andnewcommands--dirvs--pathnaming across all commands