[cli-consistency] CLI Consistency Issues - 2026-05-15

[github-actions]

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

1. Inconsistent -v/--verbose handling (1 command)

   • outcomes defines its own local --verbose flag with different wording, shadowing the global flag

2. Inconsistent flag descriptions for --cool-down (2 commands)

   • deploy and update describe the same flag differently

3. Undocumented constraint in --days flag (1 command)

   • forecast says "must be 7 or 30" in the description but the flag definition doesn't reflect this

4. Minor wording differences between add and add-wizard (2 commands)

   • Three-part spec description differs between the two commands

5. --after flag name could be confused with date filtering (1 command)

   • logs --after performs 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 --help flags and analyzed actual output

Findings Summary

✅ No issues found in these areas:

• All commands have proper --help (-h) flags
• Consistent use of --repo / -r flag across commands
• Consistent --json / -j flag formatting
• --engine / -e flag consistent across commands
• Global --banner and --verbose flags present on all commands (except outcomes — see Finding 1)
• All subcommand groups (mcp, pr, secrets, project, completion) have proper help
• Examples sections present in all commands
• Consistent workflow-id definition paragraph across applicable commands

⚠️ Issues found:

• outcomes: local verbose flag overrides global with different wording
• deploy vs update: --cool-down description inconsistency
• forecast: --days constraint not reflected in flag description
• add vs add-wizard: three-part workflow spec documented differently
• logs --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:

1. Different description wording from every other command
2. The verbose flag does not appear in the Global Flags section for this command
3. Misaligned spacing in the --banner global 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:

1. Capitalization/hyphenation: "Cool-down" (hyphenated) vs "Cooldown" (one word)
2. Missing clarification: deploy omits "(0 to disable)" which is useful documentation
3. Missing scope note: deploy omits "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