Command Line Interface Guidelines

16 days ago

A guide to designing modern command-line programs, balancing traditional UNIX principles with human-centric improvements.
Authors include Aanand Prasad, Ben Firshman, Carl Tashian, and Eva Parish, with contributions from other industry experts.
The guide advocates for human-first design, emphasizing usability, discoverability, and empathy without sacrificing UNIX composability and consistency.
Key guidelines include using argument parsing libraries, providing extensive help text, sending primary output to stdout and errors to stderr.
Output should be human-readable by default, with machine-readable options like --json, and use color, formatting, and emoji intentionally.
Errors should be caught and rewritten for clarity, with suggestions for corrections and easy bug reporting.
Arguments and flags should follow standards, prefer flags over args for clarity, and avoid secrets in flags for security.
Interactivity should only occur in TTY contexts, with prompts and confirmations for dangerous actions, and clear escape mechanisms.
Subcommands should be consistent and avoid ambiguous names, with robustness features like input validation, timeouts, and parallel execution.
Configuration follows a precedence order (flags > env variables > config files), and distribution should favor single binaries with easy uninstallation.
Analytics collection requires explicit consent or opt-out transparency, with alternatives like web docs and user feedback recommended.

Hasty Briefsbeta