CLI Design Guidelines

Use this skill when designing, reviewing, or refactoring command-line tools or scripts. Emphasize human-first UX, composability, clear help/output/error behaviors, and predictable flags/subcommands.

Source & Attribution

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.

When to Use

• 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

Design Philosophy (Condensed)

• 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.

Practical Guidelines

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.

CLI Review Checklist

• 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

Examples (Templates)

Help (human-scannable)

usage: mytool <command> [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 <path>

Progress

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

Reference Links

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