designing-clis
npx machina-cli add skill technicalpickles/pickled-claude-plugins/designing-clis --openclawDesigning 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
Source
git clone https://github.com/technicalpickles/pickled-claude-plugins/blob/main/plugins/dev-tools/skills/designing-clis/SKILL.mdView on GitHub Overview
Modern CLIs are conversations between humans and machines. Great CLIs feel discoverable, responsive, and forgiving, while poor ones leave users guessing and frustrated. The core principle is that every CLI interaction should answer: What happened? What can I do? What's next?
How This Skill Works
This skill translates UX principles, visual techniques, and practical patterns into CLI design. It draws on the Six UX Principles and Five Visual Techniques to guide command structure, output formatting, and error messaging. It provides a framework to audit, design, and iterate on commands, outputs, and help text for better discoverability and forgiveness.
When to Use It
- Building a new CLI under time pressure to establish usable defaults, help, and outputs early.
- Adding to an existing CLI to preserve UX consistency while expanding functionality.
- Fixing a confusing CLI by conducting UX audits and implementing clearer outputs and guidance.
- Designing command structure and flags to improve familiarity and discoverability.
- Improving output formatting, error messages, and help text for clarity and usability.
Quick Start
- Step 1: Audit your CLI against the Six UX Principles and Five Visual Techniques.
- Step 2: Update help text, usage, examples, and add meaningful progress indicators.
- Step 3: Validate changes with user feedback and iterate on findings.
Best Practices
- Prioritize Familiarity by using known conventions (--help, --version, verb-noun).
- Make Discoverability automatic with helpful prompts, examples, and consistent help text.
- Provide Feedback with progress indicators, confirmations, and status updates.
- Structure Output using spacing, alignment, and a clear hierarchy for scan-ability.
- Ensure Forgiveness by handling errors gracefully with clear messages and actionable guidance
Example Use Cases
- A CLI showing progress during long-running operations and providing timely confirmations.
- Error messages that explain what happened, what is valid, and how to fix the issue.
- Every command ships with --help including usage, examples, and common flags.
- Color used with text and a --no-color option to maintain accessibility.
- Structured output with sections, spacing, and bullet lists to improve readability.
