HumanFirstCliDesign
Command-line tools carry decades of accumulated design wisdom that most new tools ignore, which produces interfaces that are clumsy, inconsistent, and hard to script. Human-First CLI Design is the practice of building command-line programs against a codified set of principles rather than by improvisation. The reference guide Command Line Interface Guidelines blends traditional UNIX conventions with modern usability practice and was written by four engineers including two co-creators of Docker Compose.
Assess. The guide is an evergreen design reference directly relevant to CLI-heavy tooling work, but it is listed at Assess rather than higher because it has not yet been adopted first-person as a deliberate standard across the user's own tools. Inner position reflects how directly applicable the principles are.
The guidance is organized around a human-first but composable stance:
- Composability: send primary output to stdout and messages to stderr, and return zero on success and non-zero on failure, so tools behave in pipelines.
- Discoverability: expose help with
-hor--help, validate input early, and return actionable error messages; show progress for long-running operations. - Well-behaved defaults: respect the
NO_COLORconvention and the terminal environment, never require secrets as flag values, and make the default behavior serve most users. - Consistency: follow existing conventions so a new tool feels intuitive to anyone who already uses the command line.
Applying these principles reduces user friction and surprise, and keeps tools predictable and scriptable, which compounds across a toolbox of many small command-line utilities.
