cli-ux-designer

What this skill does

# CLI Design Guide

Expert CLI design consultant specializing in creating exceptional command-line interfaces. Design, review, and improve CLI tools by applying comprehensive design principles and patterns.

## When NOT to Use This Skill

Do not use this skill for:
- GUI/web interface design
- Backend API design (unless CLI tool interacts with it)
- General UX design outside command-line contexts
- Programming language design

## Core Expertise

Core design principles to apply:

### 1. Reasonable Defaults, Easy Overrides

- Optimize for common use cases while providing customization options
- Use flags to modify default behaviors
- Consider what most users need most often

### 2. Maintain Brand Consistency

- Use platform-specific language and terminology
- Mirror web interface patterns where appropriate
- Apply consistent visual styling (colors, states, syntax)
- Use sentence case, not title case

### 3. Reduce Cognitive Load

- Include confirmation steps for risky operations
- Provide clear headers for context
- Maintain consistent command patterns
- Anticipate user mistakes and next actions
- Design for accessibility

### 4. Terminal-First with Web Integration

- Keep users in terminal when possible
- Provide easy paths to web interface when needed
- Include `--web` flags for browser actions
- Output relevant URLs after operations

## Command Structure Expertise

Ensure commands follow this consistent pattern:

| tool | `<command>` | `<subcommand>` | [value]  | [flags] | [value] |
| ---- | ----------- | -------------- | -------- | ------- | ------- |
| cli  | issue       | view           | 234      | --web   | -       |
| cli  | pr          | create         | -        | --title | "Title" |
| cli  | repo        | fork           | org/repo | --clone | false   |

**Components:**

- **Command**: The object to interact with
- **Subcommand**: The action to take on that object
- **Flag**: Modifiers with long version (`--state`) and often shorthand (`-s`)
- **Values**: IDs, owner/repo pairs, URLs, branch names, file names

**Language Guidelines:**

- Use unambiguous language that can't be confused
- Use shorter phrases when possible and appropriate
- Use flags for modifiers of actions, avoid making modifiers their own commands
- Use understood shorthands to save characters

## Decision Frameworks

Use these when making CLI design choices:

**Flag vs. Subcommand:**
- Flag: modifies HOW a command runs (`--verbose`, `--format json`, `--dry-run`)
- Subcommand: defines WHAT action to take (`issue create`, `pr merge`)
- Rule: if it changes the action, it's a subcommand. If it changes the behavior, it's a flag.

**Interactive vs. Non-interactive:**
- Default to interactive when: user is exploring, multiple choices needed, destructive action requires confirmation
- Default to non-interactive when: command is commonly scripted, output is piped, CI/CD context
- Always: provide `--yes`/`-y` to skip confirmations, `--no-input` to disable all prompts

**Output Format:**
- Human-readable (default): colors, tables, summaries when stdout is a TTY
- Machine-readable (piped): no colors, tab-delimited or JSON when stdout is not a TTY
- Explicit: `--format json|table|csv` flag to override detection

**Error Handling:**
- Exit code 0: success
- Exit code 1: general error
- Exit code 2: usage error (wrong flags/args)
- Always: error message to stderr, suggested fix when possible

## Visual Design System Knowledge

### Typography

- Assume monospace fonts
- Use **bold** for emphasis and repository names
- Create hierarchy with spacing and weight
- No italics (unreliable support)

### Color Usage

Apply the 8 basic ANSI colors:

- **Green**: Success, open states
- **Red**: Failure, closed states
- **Yellow**: Warnings, draft states
- **Blue**: Information, links
- **Cyan**: Branch names, special identifiers
- **Magenta**: Special highlights
- **Gray**: Secondary information, labels
- **White/Default**: Primary text

**Guidelines:**

- Only enhance meaning, never communicate meaning solely through color
- Consider users can customize terminal colors
- Some terminals don't support 256-color sequences reliably

For complete ANSI color codes and escape sequences, see `./references/ansi-color-reference.md`.

### Iconography

Use Unicode symbols consistently:

- `✓` Success
- `✗` Failure
- `!` Alert
- `-` Neutral
- `+` Changes requested

Consider varying Unicode font support across systems.

For a comprehensive list of CLI-friendly Unicode symbols, see `./references/unicode-symbols.md`.

## Component Pattern Expertise

### Lists

- Use tabular format with headers
- Show state through color
- Include relevant contextual information

For a complete list view example, see `./references/examples/list-view-example.txt`.

### Detail Views

- Show comprehensive information
- Indent body content
- Include URLs at bottom

### Prompts

- **Yes/No**: Default in caps, for confirmations
- **Short text**: Single-line input with autocomplete
- **Long text**: Multi-line with editor option
- **Radio select**: Choose one option
- **Multi-select**: Choose multiple options
- Always provide flag alternatives to prompts

For an interactive prompt example, see `./references/examples/interactive-prompt-example.txt`.

### Help Pages

Required sections: Usage, Core commands, Flags, Learn more, Inherited flags
Optional sections: Additional commands, Examples, Arguments, Feedback

For a complete help text example, see `./references/examples/help-text-example.txt`.

### Syntax Conventions

- `<required-args>` in angle brackets
- `[optional-args]` in square brackets
- `{mutually-exclusive}` in braces
- `repeatable...` with ellipsis
- Use dash-case for multi-word variables

## Anti-patterns

Avoid these common CLI design mistakes:

| Anti-pattern | Better Approach |
|-------------|-----------------|
| Deeply nested subcommands (`tool group sub action`) | Max 2 levels: `tool command [flags]` |
| Inconsistent flag naming (`--no-color` vs `--disable-colors`) | Pick one convention and apply everywhere |
| Interactive prompts with no flag alternatives | Every prompt must have a `--flag` equivalent |
| Cryptic error messages ("Error: 1") | Include what went wrong, why, and how to fix |
| Silent failures (exit 0 on error) | Non-zero exit codes for failures, stderr for errors |
| Missing `--help` on subcommands | Every command level should have help |
| Mixing stdout data with status messages | Data to stdout, progress/status to stderr |

## Technical Considerations

### Script Automation Support

- Provide flags for all interactive elements
- Output machine-readable formats when piped
- Use tabs as delimiters for structured data
- Remove colors/formatting in non-terminal output
- Include exact timestamps and full data

### Accessibility

- Use punctuation for screen reader pauses
- Don't rely solely on color for meaning
- Support high contrast and custom themes
- Design for cognitive accessibility

## Success Criteria

Recommendations are successful when:
- Commands follow consistent patterns across the tool
- Help text is clear with useful examples
- Visual hierarchy guides users naturally
- Both interactive and scriptable use cases work
- Accessibility requirements are met