Repository navigation
Description
Summary
Automated CLI consistency inspection found 5 inconsistencies in command help text that should be addressed for better user experience and documentation clarity.
Breakdown by Severity
- High: 0 (Breaks functionality)
- Medium: 3 (Inconsistent behavior/misleading descriptions)
- Low: 2 (Minor inconsistencies)
Issue Categories
-
Inconsistent
-v/--verbosehandling (1 command)outcomesdefines its own local--verboseflag with different wording, shadowing the global flag
-
Inconsistent flag descriptions for
--cool-down(2 commands)deployandupdatedescribe the same flag differently
-
Undocumented constraint in
--daysflag (1 command)forecastsays "must be 7 or 30" in the description but the flag definition doesn't reflect this
-
Minor wording differences between
addandadd-wizard(2 commands)- Three-part spec description differs between the two commands
-
--afterflag name could be confused with date filtering (1 command)logs --afterperforms cache eviction, not run filtering, despite the flag name
Inspection Details
- Total Commands Inspected: 33
- Commands with Issues: 5
- Date: 2026-05-15
- Method: Executed all CLI commands with
--helpflags and analyzed actual output
Findings Summary
✅ No issues found in these areas:
- All commands have proper
--help(-h) flags - Consistent use of
--repo/-rflag across commands - Consistent
--json/-jflag formatting --engine/-eflag consistent across commands- Global
--bannerand--verboseflags present on all commands (exceptoutcomes— see Finding 1) - All subcommand groups (
mcp,pr,secrets,project,completion) have proper help - Examples sections present in all commands
- Consistent
workflow-iddefinition paragraph across applicable commands
outcomes: local verbose flag overrides global with different wordingdeployvsupdate:--cool-downdescription inconsistencyforecast:--daysconstraint not reflected in flag descriptionaddvsadd-wizard: three-part workflow spec documented differentlylogs --after: flag name is potentially misleading
Detailed Findings
1. outcomes — Local --verbose Flag Overrides Global With Different Description
Command Affected: gh aw outcomes
Priority: Medium
Type: Inconsistency
Current Output (from ./gh-aw outcomes --help):
-v, --verbose Show detailed output
Global Flags:
--banner Display ASCII logo banner with purple GitHub color theme
Expected (all other commands show):
Global Flags:
--banner Display ASCII logo banner with purple GitHub color theme
-v, --verbose Enable verbose output showing detailed information
Issue: The outcomes command declares its own local -v, --verbose flag with description "Show detailed output", which shadows the global verbose flag. This causes:
- Different description wording from every other command
- The verbose flag does not appear in the Global Flags section for this command
- Misaligned spacing in the
--bannerglobal flag (1 space vs 4 spaces in other commands)
Source: pkg/cli/outcomes_command.go:62: cmd.Flags().BoolP("verbose", "v", false, "Show detailed output")
Suggested Fix: Remove the local flag declaration and use the global persistent flag via cmd.InheritedFlags(), or at minimum align the description to match the global standard: "Enable verbose output showing detailed information".
2. deploy vs update — Inconsistent --cool-down Flag Description
Commands Affected: gh aw deploy, gh aw update
Priority: Medium
Type: Inconsistency
Current Output:
gh aw deploy --help:
--cool-down string Cool-down period before applying a new release during update (e.g. 7d, 24h, 0) (default "7d")
gh aw update --help:
--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")
Issues:
- Capitalization/hyphenation: "Cool-down" (hyphenated) vs "Cooldown" (one word)
- Missing clarification:
deployomits "(0 to disable)" which is useful documentation - Missing scope note:
deployomits "Does not apply to actions/* or github/* repositories"
Source: pkg/cli/deploy_command.go:102 vs pkg/cli/update_command.go:145
Suggested Fix: Align both descriptions. Preferred form: "Cooldown period before applying a new release (e.g. 7d, 24h, 0 to disable). Does not apply to actions/* or github/* repositories"
3. forecast — --days Constraint Not Reflected in Flag Description
Command Affected: gh aw forecast
Priority: Medium
Type: Missing documentation
Current Output (from ./gh-aw forecast --help):
--days int Historical window in days to sample run history; must be 7 or 30 (default 30)
Issue: The description says "must be 7 or 30" which is a validation constraint. However, the flag type is int with no enforcement visible in the help text (no enum-style display). Users passing e.g. --days 14 will get a runtime validation error that isn't telegraphed by the flag type. The constraint is documented in the long description body but not in the individual flag description where it matters most. The current description is actually already correct — but it could be made even clearer by noting what happens on invalid input.
Suggested Fix: Keep as-is, OR surface this as an enum in the flag type: --days {7|30} (not natively supported by cobra, but achievable via ValidArgs).
4. add vs add-wizard — Inconsistent Three-Part Workflow Spec Description
Commands Affected: gh aw add, gh aw add-wizard
Priority: Low
Type: Inconsistency
gh aw add --help (three-part spec):
- Three+ parts without .md: "owner/repo/folder[`@version`]" (loads nested aw.yml package when present)
gh aw add-wizard --help (three-part spec):
- Three+ parts without .md: "owner/repo/path[`@version`]" (tries path/aw.yml; if path is a single segment and no manifest is found, falls back to workflows/path.md)
Issue: The two commands document the same workflow spec format differently. add-wizard describes additional fallback behavior ("falls back to workflows/path.md") and uses "path" vs "folder". If the behavior is actually the same, the descriptions should be identical. If the behavior differs, that is a functional concern.
Suggested Fix: Align the descriptions. If behavior is the same, use the more detailed add-wizard description in both commands.
5. logs --after — Flag Name Could Be Confused With Date Filtering
Command Affected: gh aw logs
Priority: Low
Type: Potentially misleading naming
Current Output (from ./gh-aw logs --help):
--after string (Cache eviction) Evict locally cached run folders for runs before this date, prior to downloading...
Issue: The flag name --after strongly implies "filter to runs after this date" (similar to --start-date). However, it only performs local cache eviction and does not filter which runs are fetched. The (Cache eviction) prefix in the description helps, but users may still be confused when --after -1w does not limit fetched runs.
Also note the semantics are inverted: --after -1w evicts runs before the last week (i.e., older than 1 week), which is the opposite of what "after" implies by name.
Suggested Fix: Consider renaming to --evict-before or --cache-before to clarify the cache-eviction purpose and correct the directional semantics.
Generated by ✅ CLI Consistency Checker · ● 9.3M · ◷
- expires on May 17, 2026, 1:48 PM UTC
Activity