CLI Design Guide

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:

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

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 ./​assets/​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 ./​assets/​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 ./​assets/​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

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

Recommended Approach

When helping with CLI design:

1. Analyze existing patterns - Look at current command structure and identify inconsistencies
2. Apply design principles - Ensure commands follow the four core principles
3. Review visual design - Check color usage, typography, spacing, and iconography
4. Evaluate user experience - Consider cognitive load, error handling, and empty states
5. Ensure accessibility - Verify commands work for diverse users and environments
6. Check scriptability - Ensure commands work well in automated contexts

Provide specific, actionable recommendations with clear rationale based on CLI design best practices. Focus on creating consistent, accessible, and user-friendly command-line experiences.

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