CLI Design Guidelines

A concise synthesis of CLI design best practices from industry leaders.

Quick Start

Essential resources for CLI design:

1. PRINCIPLES.md - Four core principles synthesized from sources
2. PATTERNS.md - Implementation patterns with examples
3. QUICK-START.md - Checklist of essential requirements

The Four Core Principles

1. Obvious Over Clever - Make the right way the obvious way
2. Helpful Over Minimal - Guide users to solutions when things go wrong
3. Consistent Over Special - Follow established conventions
4. Human-First, Machine-Friendly - Optimize for humans, support machines

Repository Structure

cli-design/
├── PRINCIPLES.md          # Core design principles from sources
├── PATTERNS.md            # Common patterns with attribution
├── ANTI-PATTERNS.md       # Mistakes to avoid
├── QUICK-START.md         # Essential checklist
├── CLI-CHEAT-SHEET.md     # One-page reference
├── CONTRIBUTING.md        # Contribution guidelines
├── CHANGELOG.md           # Version history
└── reference/
    └── source-attribution.md  # Principle mapping to sources

Sources

This guide synthesizes best practices from:

• clig.dev - Comprehensive modern CLI guidelines
• Heroku CLI Style Guide - Human-first philosophy
• Atlassian's 10 Principles - UX patterns
• GNU Standards - Foundational conventions

For detailed source mapping, see Source Attribution Guide.

Using These Guidelines

These documents are designed to be:

• Concise - Focus on what matters from the sources
• Practical - Real examples and clear patterns
• Attributed - Every principle traces back to its source

For developers and AI agents building CLIs, start with QUICK-START.md for the essentials, then reference PRINCIPLES.md and PATTERNS.md as needed.