cli-design-cli-design

name	cli-design-cli-design
description	Use when designing or changing a command-line interface, including commands, arguments, output, prompts, errors, exit status, help, and automation behavior; extends core UX and contract rules for terminal interfaces.

CLI Design

Apply core-design-ux-and-flows, core-build-apis-and-contracts, and the accessibility baseline. The command line is both a human interface and a programmable contract; preserve both.

Design the command grammar

• Use a verb or verb-noun subcommand for actions; use positional arguments only for required, obvious operands and named flags for optional or ambiguous input.
• Keep names predictable across commands. Reserve short flags for frequent, unambiguous options; every short flag has a long form.
• Make repeated execution safe where practical. Require explicit confirmation or a force flag for destructive actions and show the exact scope before execution.
• Read precedence as command flag, environment/config value, then documented default. Expose a way to identify the resolved configuration without printing secrets.

Separate human and machine output

Write primary results to stdout and diagnostics/progress to stderr. Provide a documented stable machine format such as --json when automation is a supported consumer; never mix decoration into it. Treat field names and exit statuses as public contracts under core compatibility rules.

Use color only when supported and never as the sole carrier of meaning. Respect NO_COLOR and TTY detection. Avoid animated progress in non-interactive output; provide quiet and verbose modes when the task warrants them.

Make automation first-class

• Never prompt when stdin is not interactive. Accept all required values through flags, stdin, environment, or config, and fail with an actionable message when one is absent.
• Make cancellation respond promptly, clean up partial work, and return a failure status.
• Use 0 for success and stable non-zero statuses for meaningful caller decisions. Document any statuses beyond a general failure.
• Keep stdout deterministic enough to pipe. Add -- support when operands may begin with a dash.

Write help and errors

The root help states the purpose and available commands. Command help includes usage, arguments, defaults, side effects, examples, environment/config inputs, and exit behavior. Errors state what failed, why when safe, and the next corrective action; redact tokens, credentials, and sensitive paths. Suggest likely corrections for unknown commands or flags.

Completion gate

Exercise help, success, invalid input, missing configuration, destructive confirmation, non-interactive execution, piped output, JSON output, cancellation, no-color mode, and each stable exit status. The observed behavior must match the documented contract.