[cli-consistency] CLI Consistency Issues - 2026-04-01

[github-actions]

Summary

Automated CLI consistency inspection found 4 inconsistencies across help text and formatting that should be addressed for better user experience.

Breakdown by Severity

• High: 0
• Medium: 2 (confusing/misleading)
• Low: 2 (minor inconsistencies)

Issue Categories

1. Help text formatting (1 command) — hard-coded column width breaks alignment for long command names
2. Confusing flag description (1 command) — unrelated context leak in flag description
3. Documentation gap (1 command) — undocumented behavior case
4. Test coverage gap (9 commands) — group assignments not verified in integration tests

Inspection Details

• Total Commands Inspected: 32 (all commands with --help, including subcommands)
• Commands with Issues: 3
• Date: 2026-04-01
• Method: Built binary with make build, executed all CLI commands with --help flags, and analyzed actual output against source code

Findings Summary

✅ No issues found in these areas:

• Command descriptions: clear, consistent style throughout
• Flag naming: consistent use of standard flags (-r/--repo, -j/--json, -e/--engine, -o/--output, -v/--verbose)
• Cross-references between commands (add ↔ add-wizard, update ↔ upgrade) are accurate
• Examples in help text are well-formed and match documented behavior
• --repeat semantics documented consistently across run and trial
• workflow-id terminology used consistently across commands
• github.github.com domain in project new is correct (confirmed in astro.config.mjs)

⚠️ Issues found:

• Hard-coded format width in custom UsageFunc causes hash-frontmatter to be misaligned
• logs --timeout flag leaks irrelevant context about the trial command
• mcp add help omits the behavior when called with only a workflow argument
• command_groups_test.go lacks group-assignment coverage for 9 commands

Detailed Findings

1. hash-frontmatter Misaligned in Main Help Output

Command Affected: Main gh aw --help output, Utilities section
Priority: Medium
Type: Formatting bug

Current Output (from running ./gh-aw --help):

Utilities:
  completion  Generate shell completion scripts for gh aw commands
  hash-frontmatter Compute the frontmatter hash for a workflow
  mcp-server  Run an MCP (Model Context Protocol) server exposing gh aw commands as tools
  pr          Pull request utilities
  project     Manage GitHub Projects V2

Issue: hash-frontmatter description is not aligned with the rest of the Utilities section. Every other command description starts at column 14 (2-space indent + 10 chars + 2 spaces), but hash-frontmatter (16 chars) starts at column 19 (2-space indent + 16 chars + 1 space). This is caused by a hard-coded %-11s format specifier in the custom UsageFunc at cmd/gh-aw/main.go lines 536, 544, and 552:

fmt.Fprintf(out, "\n  %-11s %s", sub.Name(), sub.Short)

For command names longer than 11 characters, %-11s provides no padding, resulting in only the single literal space before the description. hash-frontmatter (16 chars) is the only command in the entire CLI that exceeds 11 characters.

Suggested Fix: Compute the max command name length dynamically within each group and use that for alignment, or increase the hard-coded width to accommodate hash-frontmatter:

// Dynamic width per group:
maxLen := 11
for _, sub := range cmds {
    if sub.GroupID == group.ID && len(sub.Name()) > maxLen {
        maxLen = len(sub.Name())
    }
}
fmtStr := fmt.Sprintf("\n  %%-%ds %%s", maxLen)
for _, sub := range cmds {
    if sub.GroupID == group.ID && (sub.IsAvailableCommand() || sub.Name() == "help") {
        fmt.Fprintf(out, fmtStr, sub.Name(), sub.Short)
    }
}
```

---

#### 2. Confusing Cross-Command Note in `logs --timeout` Flag Description

**Command Affected**: `gh aw logs`
**Priority**: Medium
**Type**: Misleading documentation

**Current Output** (from running `./gh-aw logs --help`):
```
--timeout int           Download timeout in seconds (0 = no timeout; note: trial uses minutes for its timeout)

Issue: The parenthetical note "note: trial uses minutes for its timeout" is irrelevant context for users of the logs command. Users consulting logs --help don't need to know about the trial command's timeout units. This note was likely added to clarify a distinction during development, but it creates confusion by introducing a cross-command reference mid-sentence in a flag description.

Source: pkg/cli/logs_command.go, line 199.

Suggested Fix: Remove the cross-command note or separate it into a dedicated note section:

logsCmd.Flags().Int("timeout", 0, "Download timeout in seconds (0 = no timeout)")
```

---

#### 3. `mcp add` Help Missing Behavior for Single-Argument Case

**Command Affected**: `gh aw mcp add`
**Priority**: Low
**Type**: Documentation gap

**Current Output** (from running `./gh-aw mcp add --help`):
```
When called with no arguments, it will show a list of available MCP servers from the registry.
...
Usage:
  gh aw mcp add [workflow] [server] [flags]

Examples:
  gh aw mcp add                                          # List available MCP servers
  gh aw mcp add weekly-research makenotion/notion-mcp-server  # Add Notion MCP server
```

**Issue**: The help text documents two extreme cases: zero arguments (list servers) and two arguments (workflow + server), but says nothing about what happens when only a workflow name is provided without a server name. Users unfamiliar with the command may try `gh aw mcp add my-workflow` and encounter unexpected behavior without guidance.

**Suggested Fix**: Add documentation for the single-argument case to the long description and/or examples:
```
When called with only a workflow ID (no server), it will show available servers and prompt for selection.
```
Or add an example:
```
gh aw mcp add weekly-research                                  # Show servers and prompt for selection

---

4. command_groups_test.go Missing Group-Assignment Coverage

File Affected: cmd/gh-aw/command_groups_test.go
Priority: Low
Type: Test coverage gap

Issue: The integration test TestCommandGroupAssignments verifies group assignments for 14 commands but does not include these 9 commands that also have explicit group assignments in main.go:

• hash-frontmatter → utilities
• domains → development
• validate → development
• completion → utilities
• upgrade → setup
• project → utilities
• add-wizard → setup
• checks → analysis
• health → analysis

If a future refactor accidentally removes a GroupID assignment (like the one that would expose the hash-frontmatter formatting bug above), these commands would silently move to "Additional Commands" without any test failing.

Suggested Fix: Add the missing 9 commands to the test case slice in TestCommandGroupAssignments.

Generated by CLI Consistency Checker · ◷

• expires on Apr 3, 2026, 1:45 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot coding agent.

The Copilot coding agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

🍪 Om nom nom by Issue Monster · ◷