Designing CLIs
Overview
Modern CLIs are conversations between human and machine. Great CLIs feel discoverable, responsive, and forgiving. Poor CLIs leave users guessing, waiting, and frustrated.
Core principle: Every CLI interaction should answer: "What happened? What can I do? What's next?"
When to Use
Building:
- •Creating new CLI commands or tools
- •Designing output format, error messages, progress indicators
- •Planning CLI architecture (flags, subcommands, interaction model)
Improving:
- •Enhancing existing CLI user experience
- •Adding features to existing commands
- •Making CLI "less confusing" or "easier to use"
Reviewing:
- •Auditing CLI code for UX issues
- •Responding to user complaints about difficulty
- •Troubleshooting discoverability problems
Quick Decision Framework
| Working On | Read This |
|---|---|
| New CLI under time pressure | practical-patterns.md (Priority Checklist) |
| Adding to existing CLI | practical-patterns.md (Working with Existing CLIs) |
| Fixing "confusing" CLI | practical-patterns.md (CLI UX Audit Checklist) |
| Command structure, flags | ux-principles.md (Familiarity, Discoverability) |
| Output formatting | visual-techniques.md (Layout, Spacing, Color) |
| Error messages, help text | practical-patterns.md (Error Message Patterns) |
| Overall architecture | ux-principles.md (complete overview) |
The Six UX Principles
- •Familiarity - Use known conventions (--help, --version, verb-noun)
- •Discoverability - Guide users (help text, prompts, examples)
- •Feedback - Show what's happening (progress, confirmations, state)
- •Clarity - Structure output (spacing, alignment, hierarchy)
- •Flow - Minimize friction (shortcuts, defaults, scriptability)
- •Forgiveness - Handle errors gracefully (clear messages, suggestions, safety)
See ux-principles.md for detailed guidance and examples.
The Five Visual Techniques
- •Color - Semantic meaning (green=success, red=error, yellow=warning)
- •Spacing - Visual grouping (blank lines, indentation, alignment)
- •Layout - Structured regions (panels, blocks, persistent areas)
- •Symbols - Fast signifiers (✓ ✗ ⚠ →, checkboxes, progress indicators)
- •Structured Feedback - Narrative output (phases, lists, visible progress)
See visual-techniques.md for implementation patterns.
Common Mistakes
❌ Silent operations - No feedback during slow operations ✅ Show progress, confirmations, or at minimum "Working..."
❌ Cryptic errors without guidance - "Error: invalid input" ✅ Explain what's wrong, what's valid, how to fix: "Error: Invalid environment 'production'. Valid: dev, staging, prod"
❌ No --help text - Forces users to read docs or source ✅ Every command supports --help with usage and examples
❌ Wrong exit codes - Always returns 0, breaks scripting ✅ 0 for success, 1 for errors
❌ Color-only information - Inaccessible without color support ✅ Always pair color with text/symbols, support --no-color
❌ Walls of unstructured text - Dense output hard to scan ✅ Use spacing, alignment, hierarchy to structure information
Priority Under Time Pressure
When building CLI urgently, include these first (high impact, low effort):
- •--help flag (2 minutes) - Include usage, examples, common flags
- •Exit codes (1 minute) - 0=success, 1=error, enables CI/CD
- •Clear errors (5 minutes) - What happened + what's valid + how to fix
- •Progress feedback (3 minutes) - Show activity during slow operations
Skip initially (lower priority):
- •Color schemes (polish, not function)
- •Advanced formatting (tables, columns)
- •Multiple output formats (JSON, YAML, etc.)
Cross-References
Detailed guidance:
- •practical-patterns.md - Checklists, templates, decision trees
- •ux-principles.md - Principles with real-world examples
- •visual-techniques.md - Implementation patterns for terminal output
- •reading-list.md - Sources and deeper learning
Research materials:
- •research/ - Original blog-style documentation and analysis