Command Line Interface Guidelines
10 hours ago
- #design-guide
- #best-practices
- #command-line
- 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.