cli-design

name	cli-design
description	Guide for building delightful, human-first command-line tools with proper command structure, output formatting, error handling, configuration, and extensibility. Use when creating CLI tools, adding subcommands, designing CLI output, handling errors in CLIs, or reviewing CLI code for UX issues.

CLI Design

Build command-line tools that feel solid, communicate clearly, and compose well with the Unix ecosystem.

When to use

• Creating a new CLI tool or adding subcommands
• Designing output format (human, JSON, LLM)
• Implementing error handling and exit codes
• Adding authentication, configuration, or plugin systems
• Reviewing CLI code for usability issues

Core philosophy

1. Human-first, machine-compatible -- design for humans, then ensure machines can consume output
2. Conversation, not interrogation -- each invocation is a turn in a dialogue; suggest corrections, show next steps
3. Consistency over novelty -- follow conventions (--help, -v, --output json, exit codes)
4. Say just enough -- concise by default, verbose via flags
5. Robustness as a feeling -- fast startup, clear feedback, no hanging, no cryptic stack traces

Rule index

Rules are organized by domain and impact. See the linked reference for full details with examples.

#	Domain	Rule	Impact	Reference
1	Command	Use tool <noun> <verb> [flags] for multi-resource CLIs	CRITICAL	command-structure
2	Command	Keep subcommand nesting to 2 levels max	HIGH	command-structure
3	Command	Prefer flags over positional args (self-documenting, order-independent)	HIGH	command-structure
4	Command	Every flag has a long form; common ones also get a short form	MEDIUM	command-structure
5	Command	Support global flags: --help, --version, --verbose, --output, --no-color, --quiet	CRITICAL	command-structure
6	Output	Detect TTY -- adapt output to terminal vs pipe	CRITICAL	output-design
7	Output	stdout for data, stderr for messages/progress/errors	CRITICAL	output-design
8	Output	Support --output json with stable schema	CRITICAL	output-design
9	Output	Support --output llm for agent-friendly consumption	HIGH	output-design
10	Output	Use color for scannability, not decoration; respect NO_COLOR	MEDIUM	output-design
11	Output	Show spinners/progress for long operations on stderr	HIGH	output-design
12	Help	Show concise summary when run with no args; full help on --help	CRITICAL	help-system
13	Help	Lead with examples in help text	HIGH	help-system
14	Help	Suggest corrections on typos and next steps after actions	HIGH	help-system
15	Help	Provide shell completion for bash, zsh, fish, powershell	MEDIUM	help-system
16	Errors	Every error answers: what happened, why, and what to do	CRITICAL	error-handling
17	Errors	Use namespaced error codes (AUTH-003, NET-001)	HIGH	error-handling
18	Errors	Define clear exit code mapping (0=success, 1=general, 2=usage, etc.)	HIGH	error-handling
19	Errors	Never show raw stack traces; log to debug file	HIGH	error-handling
20	Interactive	Prompt for missing args only when stdin is TTY; fail with --no-input	HIGH	interactivity
21	Interactive	Confirm destructive actions; support --yes to bypass	CRITICAL	interactivity
22	Config	Follow XDG Base Directory (~/.config/mycli/) on all platforms	HIGH	configuration
23	Config	Precedence: flags > env vars > project config > user config > defaults	HIGH	configuration
24	Auth	Support token via flag, env var, stored creds, and interactive login	HIGH	authentication
25	Extend	Use mycli-<name> executable pattern for plugins	MEDIUM	extensibility
26	Perf	Target <100ms cold start; defer work until needed	HIGH	performance
27	Perf	Print something within 100ms; responsiveness > raw speed	HIGH	performance
28	Dist	Ship single static binary when possible	HIGH	distribution
29	Dist	Support --version with version, commit hash, build date	MEDIUM	distribution
30	Test	Integration-test full CLI invocations (stdout, stderr, exit codes)	HIGH	testing
31	Robust	Handle SIGINT (exit 130), SIGTERM (exit 143), SIGPIPE (exit silently)	HIGH	testing
32	Robust	Validate input early, bail before state changes	HIGH	error-handling
33	Robust	Design for crash-only: avoid cleanup requirements on exit	MEDIUM	testing
34	Security	Never accept secrets via flags (visible in ps, shell history)	CRITICAL	configuration
35	Future	Keep changes additive; deprecate before removing	HIGH	distribution

Workflow

When building or reviewing a CLI tool:

1. Read the relevant reference files for the domains you're working on
2. Apply rules by impact -- CRITICAL first, then HIGH, then MEDIUM
3. Use the checklist before shipping

Additional references

• Philosophy deep dive -- expanded principles with rationale
• Pre-launch checklist -- verification checklist before shipping