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
1---2name: designing-clis3description: Use when building, improving, or reviewing command-line interfaces for better user experience - before implementing commands/output/errors, when users report confusion or frustration, or when CLI feels hard to use - provides UX principles, visual design techniques, and practical patterns for creating discoverable, delightful CLIs4---5
6# Designing CLIs
7
8## Overview
9
10Modern CLIs are conversations between human and machine. Great CLIs feel discoverable, responsive, and forgiving. Poor CLIs leave users guessing, waiting, and frustrated.
11
12**Core principle:** Every CLI interaction should answer: "What happened? What can I do? What's next?"
13
14## When to Use
15
16**Building:**
17- Creating new CLI commands or tools
18- Designing output format, error messages, progress indicators
19- Planning CLI architecture (flags, subcommands, interaction model)
20
21**Improving:**
22- Enhancing existing CLI user experience
23- Adding features to existing commands
24- Making CLI "less confusing" or "easier to use"
25
26**Reviewing:**
27- Auditing CLI code for UX issues
28- Responding to user complaints about difficulty
29- Troubleshooting discoverability problems
30
31## Quick Decision Framework
32
33| Working On | Read This |
34|------------|-----------|
35| New CLI under time pressure | practical-patterns.md (Priority Checklist) |
36| Adding to existing CLI | practical-patterns.md (Working with Existing CLIs) |
37| Fixing "confusing" CLI | practical-patterns.md (CLI UX Audit Checklist) |
38| Command structure, flags | ux-principles.md (Familiarity, Discoverability) |
39| Output formatting | visual-techniques.md (Layout, Spacing, Color) |
40| Error messages, help text | practical-patterns.md (Error Message Patterns) |
41| Overall architecture | ux-principles.md (complete overview) |
42
43## The Six UX Principles
44
451. **Familiarity** - Use known conventions (--help, --version, verb-noun)
462. **Discoverability** - Guide users (help text, prompts, examples)
473. **Feedback** - Show what's happening (progress, confirmations, state)
484. **Clarity** - Structure output (spacing, alignment, hierarchy)
495. **Flow** - Minimize friction (shortcuts, defaults, scriptability)
506. **Forgiveness** - Handle errors gracefully (clear messages, suggestions, safety)
51
52See ux-principles.md for detailed guidance and examples.
53
54## The Five Visual Techniques
55
561. **Color** - Semantic meaning (green=success, red=error, yellow=warning)
572. **Spacing** - Visual grouping (blank lines, indentation, alignment)
583. **Layout** - Structured regions (panels, blocks, persistent areas)
594. **Symbols** - Fast signifiers (✓ ✗ ⚠ →, checkboxes, progress indicators)
605. **Structured Feedback** - Narrative output (phases, lists, visible progress)
61
62See visual-techniques.md for implementation patterns.
63
64## Common Mistakes
65
66❌ **Silent operations** - No feedback during slow operations
67✅ Show progress, confirmations, or at minimum "Working..."
68
69❌ **Cryptic errors without guidance** - "Error: invalid input"
70✅ Explain what's wrong, what's valid, how to fix: "Error: Invalid environment 'production'. Valid: dev, staging, prod"
71
72❌ **No --help text** - Forces users to read docs or source
73✅ Every command supports --help with usage and examples
74
75❌ **Wrong exit codes** - Always returns 0, breaks scripting
76✅ 0 for success, 1 for errors
77
78❌ **Color-only information** - Inaccessible without color support
79✅ Always pair color with text/symbols, support --no-color
80
81❌ **Walls of unstructured text** - Dense output hard to scan
82✅ Use spacing, alignment, hierarchy to structure information
83
84## Priority Under Time Pressure
85
86When building CLI urgently, include these first (high impact, low effort):
87
881. **--help flag** (2 minutes) - Include usage, examples, common flags
892. **Exit codes** (1 minute) - 0=success, 1=error, enables CI/CD
903. **Clear errors** (5 minutes) - What happened + what's valid + how to fix
914. **Progress feedback** (3 minutes) - Show activity during slow operations
92
93Skip initially (lower priority):
94- Color schemes (polish, not function)
95- Advanced formatting (tables, columns)
96- Multiple output formats (JSON, YAML, etc.)
97
98## Cross-References
99
100**Detailed guidance:**
101- practical-patterns.md - Checklists, templates, decision trees
102- ux-principles.md - Principles with real-world examples
103- visual-techniques.md - Implementation patterns for terminal output
104- reading-list.md - Sources and deeper learning
105
106**Research materials:**
107- research/ - Original blog-style documentation and analysis
majiayu000