[cli-consistency] CLI Consistency Improvements - May 2026

[github-actions]

Summary

Comprehensive CLI consistency check identified 10 minor improvements to enhance help text consistency and clarity. No critical bugs found - the CLI is well-designed overall.

Severity breakdown: 2 medium, 8 low
Overall grade: A- (93/100)

---

Medium Priority Issues

M1: Inconsistent "workflow-id" vs "pattern" Terminology

Affected commands: status, list

Issue: Most commands include this standard explanation:

The workflow-id is the basename of the Markdown file without the .md extension.
You can provide either the workflow-id (e.g., 'ci-doctor') or the full filename (e.g., 'ci-doctor.md').

But status and list use "pattern" without explanation:

Usage:
  gh aw status [pattern] [flags]
  gh aw list [pattern] [flags]

Impact: Users may be confused about what "pattern" accepts

Fix: Add brief explanation to both commands, e.g.:

The optional pattern argument filters workflows by name (case-insensitive substring match).
It accepts workflow IDs (basename without .md) or full filenames.

Files to modify:

• pkg/cli/status_command.go - Update Long description
• pkg/cli/list_command.go - Update Long description

---

M2: Example Command Verification

Affected: All commands with examples

Issue: While spot-checking confirmed examples work, comprehensive automated testing of help text examples doesn't exist.

Fix: Add test to verify:

1. All flags mentioned in examples exist
2. Example commands are syntactically valid
3. File paths in examples are correct

Suggested approach: Parse help text in tests, extract example commands, validate flags against command definition

---

Low Priority Issues

L1: Inconsistent Example Section Headers (click to expand)

Affected: logs, forecast, audit vs. others

Issue: Some commands use comment headers to group examples:

  # Basic usage
  gh aw logs                           # Download logs for all workflows
  
  # Date filtering
  gh aw logs --start-date 2024-01-01   # Download all runs after date

Most commands don't use this pattern.

Fix: Standardize approach - either:

1. Add headers to all commands with >5 examples, OR
2. Remove headers from logs/forecast/audit for consistency

Files to modify: pkg/cli/logs_command.go, pkg/cli/forecast_command.go, pkg/cli/audit_command.go

L2: Hyphenation "workflow-id" vs "workflow ID"

Affected: All commands

Issue: Inconsistent usage:

• "The workflow-id is the basename..." (hyphenated)
• "Multiple workflow IDs may be provided..." (space)

Fix: Use "workflow ID" (with space) consistently for better readability

Files to modify: All *_command.go files with workflow-id references

L3: Help Flag Period Inconsistency

Affected: All commands

Issue: Help flag descriptions lack periods:

-h, --help                       Show help for gh aw add

While other flags have them:

--force                      Overwrite existing workflow files without confirmation.

Fix: Either:

1. Add periods to help flag descriptions for consistency, OR
2. Document as intentional style (help flags are terse)

Recommendation: Keep current style (no period for help) and document it

L4: Default Value Documentation

Affected: Various flags

Issue: Some flags show defaults explicitly, others say "auto-detected":

--action-mode string          Action script inlining mode (inline, dev, release). Auto-detected if not specified

Fix: Consider showing auto-detected defaults when possible:

--action-mode string          Action script inlining mode (inline, dev, release). Auto-detected (typically: dev)

L5: Abbreviation Documentation

Affected: Multiple commands

Issue: Abbreviations used without definition:

• "MCP" (defined in gh aw mcp --help but used elsewhere)
• "GHES" (GitHub Enterprise Server)
• "SHA" (commit hash)

Fix: Add brief parenthetical definitions on first use, e.g.:

--ghes    Enable GitHub Enterprise Server (GHES) compatibility mode

L6: Spacing in Flag Lists

Affected: Multiple commands

Issue: Inconsistent vertical spacing between flag groups

Fix: Standardize spacing (cosmetic only)

L7: Short Description Style

Affected: All commands

Issue: Short descriptions in main help vary in length and detail

Fix: Review for consistent verbosity (60-80 chars ideal)

L8: Workflow Specifications Section Duplication

Affected: add, add-wizard

Issue: Both commands include identical multi-line "Workflow specifications:" sections

Recommendation: Keep as-is (completeness > DRY for CLI help). Users benefit from having complete info in each command.

---

What's Working Well ✅

1. Excellent flag consistency: --repo, --dir, --engine, --verbose completely consistent
2. Good example coverage: All 31 commands have examples
3. Clear descriptions: Nearly all flags well-documented
4. Documentation alignment: CLI help matches documentation closely
5. No critical issues: No typos, broken flags, or incorrect paths found

---

Inspection Metadata

• Commands inspected: 31 (add, add-wizard, compile, deploy, disable, enable, fix, forecast, health, init, lint, list, logs, mcp, new, outcomes, pr, project, remove, run, secrets, status, trial, update, upgrade, validate, version, audit, checks, completion, domains, hash-frontmatter, mcp-server)
• Method: Analysis of CLI help output cross-referenced with documentation
• Date: 2026-05-22
• Run: 26291830705

---

Implementation Priority

Phase 1 (Medium priority):

• M1: Add "pattern" explanation to status and list commands
• M2: Add automated example validation tests

Phase 2 (Low priority - can be batched):

• L1: Standardize example section headers
• L2: Standardize "workflow ID" terminology
• L3: Document help flag style
• L4: Improve default value hints
• L5: Add abbreviation definitions
• L6: Standardize flag spacing
• L7: Review short description consistency

Not needed:

• L8: Keep workflow specifications duplication (helps users)

Generated by ✅ CLI Consistency Checker · ● 1.5M · ◷

• expires on May 24, 2026, 1:59 PM UTC