Skip to content

Latest commit

 

History

History
133 lines (93 loc) · 3.94 KB

PRINCIPLES.md

File metadata and controls

133 lines (93 loc) · 3.94 KB

CLI Design Principles

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

The Four Core Principles

These principles synthesize wisdom from clig.dev, Heroku, Atlassian, and GNU:

1. Obvious Over Clever

Make the right way the obvious way. Users shouldn't need documentation for basic tasks.
From: Atlassian's "align with conventions", clig.dev's discoverability

# Good: Clear and self-documenting
mytool deploy --environment production --skip-tests

# Bad: Cryptic shortcuts
mytool d -e p -S

2. Helpful Over Minimal

When things go wrong, help users understand and recover.
From: Atlassian's "craft human-readable errors" & "suggest next step", clig.dev's empathy

# Good: Actionable error
Error: Config file not found at './config.yml'
Try: Run 'mytool init' to create a config file

# Bad: Cryptic error
Error: ENOENT

3. Consistent Over Special

Follow established conventions. Your clever pattern is a learning burden.
From: GNU standards, Heroku conventions, clig.dev consistency

# Good: Universal conventions
mytool --help
mytool --version

# Bad: Unique patterns
mytool /h
mytool -info

4. Human-First, Machine-Friendly

Optimize for humans by default, but provide machine-readable options.
From: Heroku's "CLI is for humans before machines", clig.dev's human-first design

# Human output (default)
$ mytool status
Service: ✓ healthy
Database: ✓ connected

# Machine output (on demand)
$ mytool status --json
{"service":{"status":"healthy"},"database":{"status":"connected"}}

Key Patterns from Sources

Help and Documentation (All sources)

  • Provide --help on every command with examples
  • Lead with common use cases
  • Make help contextual to the command

Error Messages (Atlassian #5, clig.dev)

  • Describe what went wrong clearly
  • Suggest how to fix it
  • Provide a link for more details

Progress Indicators (Atlassian #3)

  • Show progress for operations >1 second
  • Use spinners, bars, or status updates
  • Ensure users know the tool hasn't frozen

Flags Over Args (Atlassian #10, Heroku)

  • Prefer named flags to positional arguments
  • Use standard flag names (--output, --format)
  • Provide short versions for common flags (-o, -f)

Output and Formatting (Heroku, clig.dev)

  • Detect if output is to terminal or pipe
  • Use color and formatting only in terminals
  • Respect NO_COLOR environment variable
  • Provide --json for structured output

Standard Options (GNU)

  • Always support --help and --version
  • Use consistent exit codes (0=success, 1-255=error)
  • Send output to stdout, errors to stderr

Prompting (Atlassian #8)

  • Prompt for missing required information
  • Provide sensible defaults in brackets
  • Always allow --yes or --no-input for automation

Quick Checklist

Essential requirements derived from all sources:

  • Works without configuration (sensible defaults)
  • --help on every command (with examples)
  • Human-readable error messages
  • Proper exit codes (0=success)
  • Machine-readable output option (--json)
  • Progress indicators (>1 second operations)
  • Standard options (--version, --verbose, --quiet)
  • TTY detection (color only in terminals)
  • Respect NO_COLOR environment variable

References

For detailed source mapping, see Source Attribution Guide.