cli-design

# 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 1. **Familiarity** - Use known conventions (--help, --version, verb-noun) 2. **Discoverability** - Guide users (help text, prompts, examples) 3. **Feedback** - Show what's happening (progress, confirmations, state) 4. **Clarity** - Structure output (spacing, alignment, hierarchy) 5. **Flow** - Minimize friction (shortcuts, defaults, scriptability) 6. **Forgiveness** - Handle errors gracefully (clear messages, suggestions, safety) See ux-principles.md for detailed guidance and examples. ## The Five Visual Techniques 1. **Color** - Semantic meaning (green=success, red=error, yellow=warning) 2. **Spacing** - Visual grouping (blank lines, indentation, alignment) 3. **Layout** - Structured regions (panels, blocks, persistent areas) 4. **Symbols** - Fast signifiers (✓ ✗ ⚠ →, checkboxes, progress indicators) 5. **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, non-zero for failure — in `akt`, the categorized codes in SPEC.md §11.2 ❌ **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): 1. **--help flag** (2 minutes) - Include usage, examples, common flags 2. **Exit codes** (1 minute) - 0=success, non-zero=failure (SPEC.md §11.2 for `akt`), enables CI/CD 3. **Clear errors** (5 minutes) - What happened + what's valid + how to fix 4. **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