cli-design-guidelines

Based on the Command Line Interface Guidelines (clig.dev) and the Chinese translation at clig.onev.dev. Licensed under CC BY-SA 4.0. Include attribution when copying or adapting text.

• Designing a new CLI or script interface
• Adding flags, subcommands, config, or env support
• Improving help, output, and error messages
• Making tools more composable in shell pipelines
• Reducing ambiguity and surprises in CLI UX

• Human-first: optimize for humans, not just programmatic callers.
• Composable: small tools with clear interfaces; respect stdin/stdout/stderr.
• Consistent: reuse familiar conventions to reduce cognitive load.
• Say just enough: balance silence vs noisy output.
• Discoverable: help and examples make features easy to find.
• Conversational: guide the user through retries and multi-step flows.
• Robust: handle errors gracefully and look reliable.
• Empathy + chaos: expect misuse and messy real-world environments.

Help & Docs

• Always support -h and --help; keep help scannable.
• Provide usage, options, examples, and key subcommands.
• Avoid raw escape garbage in non-TTY output.

Output

• Prefer short success output over silence for humans.
• Provide -q/--quiet to suppress non-essential output.
• If state changes, explain what changed and how to inspect it.
• Suggest next commands in multi-step workflows.
• For long work, show progress; keep logs usable if errors occur.

Errors

• Rewrite errors for humans; include an actionable hint.
• Keep signal high; group repetitive errors.
• Use non-zero exit codes on failure; stderr for errors.

Args & Flags

• Prefer flags over positional args for clarity and future-proofing.
• Provide long-form flags; short only for common ones.
• Use standard flag names when possible (--help, --json, --dry-run, --quiet).
• Avoid ambiguous ordering; allow flags before/after subcommands if possible.
• Don’t force interactive input; always allow flags/args and support --no-input.

Interactivity

• Only prompt when stdin is a TTY; otherwise error with guidance.
• Provide explicit opt-out (--no-input) and safe defaults.
• For dangerous actions, confirm appropriately and support --force/--confirm.

Subcommands

• Use subcommands to reduce complexity; keep flags consistent.
• Prefer noun verb naming; avoid confusing near-duplicates.

Robustness

• Validate inputs early; fail before side effects.
• Show feedback quickly; add progress for slow ops.
• Be explicit when crossing boundaries (network/filesystem).
• Add timeouts and recoverability for transient failures.

• Help: readable, complete, examples included, -h/--help supported
• Output: concise by default, --quiet optional, progress for long tasks
• Errors: actionable hints, stderr, non-zero exit codes
• Flags: standard names, long + short where appropriate, predictable ordering
• Interactivity: TTY-only prompts, --no-input, safe confirmations
• Subcommands: consistent naming and flag behavior
• Composability: stdout machine-friendly; stderr for logs

Help (human-scannable)

```

usage: mytool [options]

commands:

init bootstrap workspace

sync fetch and apply updates

options:

-h, --help show help

-q, --quiet suppress non-essential output

--json machine-readable output

examples:

mytool init --config ./tool.yaml

mytool sync --dry-run

```

Error (actionable)

```

error: cannot write to config.yml

hint: run chmod +w config.yml or pass --config

```

Progress

```

fetching updates... 42% (12/28)

```

• clig.onev.dev (Chinese translation)
• clig.dev (original)
• CC BY-SA 4.0 license