designing-clis

# 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, r