CLI-CHEAT-SHEET.md

CLI Design Cheat Sheet

One-page reference for CLI design. Print-friendly version of essential principles and patterns.

🎯 Core Principles

Obvious Over Clever • Helpful Over Minimal • Consistent Over Special • Human-First, Machine-Friendly

✅ Quick Checklist

□ --help everywhere     □ Examples in help      □ Meaningful errors
□ Exit codes work       □ Progress >1 second    □ No config required
□ --json for machines   □ --dry-run safety      □ Piping works

📝 Command Patterns

simple-tool [options] <args>              # curl, jq, grep
tool <command> [options] [args]           # git, docker, npm
tool <resource> <action> [options]        # kubectl, aws

🚨 Error Template

Error: What went wrong
  Why it happened
  How to fix it
Example: tool <correct-usage>

🎨 Output Design

# Default: Human readable
$ tool list
NAME    STATUS   TIME
app-1   running  2h ago

# Pipe: Auto plain text
$ tool list | grep running
app-1   running   2h

# Explicit: Machine format
$ tool list --json
[{"name":"app-1",...}]

🏗️ Standard Flags

-h, --help        Help text
-v, --version     Version info
-v, --verbose     More output
-q, --quiet       Less output
-y, --yes         No prompts
-n, --dry-run     Preview only
--json            JSON output
--no-color        Plain text

🔄 Progress Patterns

# Spinner (unknown duration)
Loading... ⠼

# Bar (known duration)
[████████░░] 80% ETA: 2s

# Steps (multiple ops)
✓ Build complete
✓ Tests passed
⠼ Deploying...

💡 Quick Wins

1. Add examples to help text
2. Show progress for operations >1s
3. Suggest fixes in error messages
4. Support --dry-run for safety
5. Auto-detect TTY vs pipe

🚫 Top Anti-Patterns

❌ Mystery commands: mkcfg 3 p
❌ Useless errors: Error: ENOENT
❌ No feedback: deploying... (5 min)
❌ Required config for basics
❌ Breaking pipes and scripts

🎯 Decision Guide

Need subcommands? → More than 5 operations
Interactive mode? → Complex/dangerous operations
JSON output? → Always offer via flag
Color output? → Only in TTY, respect NO_COLOR
Config files? → Optional with good defaults

🔍 Testing Checklist

• Works with no arguments
• Pipes chain correctly
• Errors are helpful
• --help is comprehensive
• Exit codes meaningful
• Works on Win/Mac/Linux

📚 Learn More

Principles • Patterns • Anti-Patterns • Quick Start

---

Based on clig.dev, Atlassian, GNU, and Heroku guidelines. Keep this handy when designing CLIs!