Skip to content

Latest commit

 

History

History
75 lines (53 loc) · 2.16 KB

QUICK-START.md

File metadata and controls

75 lines (53 loc) · 2.16 KB

Quick Start: CLI Design Checklist

Essential requirements for building a good CLI, based on industry best practices.

Minimum Requirements

Every CLI must have:

  • --help on every command with examples (Atlassian #2, GNU)
  • Human-readable error messages with solutions (Atlassian #5)
  • Exit codes: 0=success, 1-255=errors (GNU)
  • Standard options: --version, --verbose, --quiet (GNU)
  • TTY detection: Rich output for humans, plain for pipes (Heroku, clig.dev)

Output & Formatting

  • Progress indicators for operations >1 second (Atlassian #3)
  • NO_COLOR environment variable support (Heroku)
  • --json flag for machine-readable output (Heroku, clig.dev)
  • Errors to stderr, output to stdout (GNU)
  • Suggest next steps after operations (Atlassian #7)

Command Design

  • Flags over arguments (Atlassian #10, Heroku)
  • Verb commands, plural noun topics (Heroku)
  • Confirmation prompts for destructive operations (clig.dev)
  • --yes/--no-input flags for automation (Atlassian #8)
  • Sensible defaults that work without configuration (clig.dev)

Quick Examples

Good Error Message

Error: Cannot connect to database
  Connection refused at localhost:5432

  Try:
    1. Check if PostgreSQL is running
    2. Run 'mytool config check'

Good Progress Indicator

$ mytool process large-file.csv
Processing... [████████░░] 80% (1234/1543 records)

Good Help Text

Usage: mytool deploy [OPTIONS]

Deploy application to specified environment

Options:
  -e, --env TEXT     Target environment (dev/staging/prod)
  -f, --force        Skip confirmation
  -h, --help         Show this message

Examples:
  mytool deploy --env staging
  mytool deploy -e prod --force

References

This checklist synthesizes: