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

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