CLI Design Guidelines

Condensed from clig.dev — an open-source guide to writing better command-line programs, updating UNIX principles for the modern day.

When reviewing or building a CLI, work through each section below as a checklist. The examples are as important as the rules — they show what good looks like.

Core Philosophy

1. Human-first design — If a command is used primarily by humans, design for humans first. Shed the baggage of machine-first UNIX conventions where they hurt usability.
2. Simple parts that work together — Composability matters. Respect stdin/stdout/stderr, exit codes, signals, and line-based text. Use JSON when structure is needed. Your software will become a part in a larger system — your only choice is whether it will be a well-behaved part.
3. Consistency across programs — Follow existing CLI conventions. Users have muscle memory. Break convention only with care and good reason. When convention would compromise usability, it might be time to break with it — but make the decision deliberately.
4. Say just enough — A command hanging silently for minutes is as bad as dumping pages of debug output. Both leave the user confused. Clarity over volume.
5. Ease of discovery — Comprehensive help, lots of examples, suggest next commands, suggest fixes on errors. Steal ideas from GUIs. Remember-and-type and see-and-point are not mutually exclusive.
6. Conversation as the norm — CLI interaction is conversational. Users learn through trial-and-error, multi-step workflows (multiple git adds then git commit), exploration (cd and ls to understand a directory), and dry-runs before real runs. Guide users through the conversation — suggest corrections, show intermediate state, confirm before scary actions. At best, it's a pleasant exchange that speeds them on their way. At worst, it's hostile and makes them feel stupid.
7. Robustness — Both objective (handle unexpected input gracefully, be idempotent) and subjective (feel solid, not flimsy). Keep users informed, explain common errors, don't print scary stack traces. Simplicity breeds robustness.
8. Empathy — Give users the feeling you're on their side, that you want them to succeed, that you've thought carefully about their problems. Delight means exceeding expectations at every turn.
9. Chaos — The terminal is a mess. Inconsistencies are everywhere. Yet this chaos has been a source of power — few constraints means all manner of invention. Sometimes you should break the rules. Do so with intention and clarity of purpose. "Abandon a standard when it is demonstrably harmful to productivity or user satisfaction." — Jef Raskin

The Basics