| name | cli-ux |
| description | Design, implement, refactor, or review line-oriented command-line interfaces across any language or renderer. Use when changing commands, flags, help, prompts, confirmations, progress, errors, warnings, results, lists, tables, output layout, colors, stdout/stderr, machine formats, TTY behavior, non-interactive behavior, destructive actions, streams, wrappers, or CLI compatibility. Do not use for internal refactors with no observable CLI change or for full-screen terminal UIs. |
CLI UX
Create clear, scriptable line-oriented CLIs with one exact human-output style.
Treat Fish, shell, Gum, Clack, Rich, Charmbracelet, Cobra, Click, and plain ANSI as renderers. Choose the smallest renderer that fits the interaction; do not let a renderer define the visible design.
Classify First
Classify each command or subcommand before changing its output. A command can have more than one profile.
| Profile | Primary contract |
|---|
| Human workflow | Guided task completion |
| Query or report | Scannable human result |
| Filter | Exact transformed records |
| Machine protocol | Stable documented data |
| Interactive command | Prompt and selection flow |
| Live stream | Ordered ongoing records |
| Transparent wrapper | Preserve child behavior |
| CI adapter | Preserve CI control protocol |
| Stable public CLI | Preserve compatibility |
Answer before implementation:
- Who consumes stdout and stderr?
- Is stdin payload, prompt input, or unused?
- Is output already a stable text or machine protocol?
- Does a child process own either stream or the terminal?
- Which modes exist: TTY, pipe, CI, no-input, plain, JSON, JSONL?
- Which compatibility contracts must remain unchanged?
Workflow
- Identify the user job, target, side effects, failure states, and recovery path.
- Map every observable surface: context, resolved state, prompt, preview, progress, result, warning, error, empty state, list, detail, stream, and machine record.
- Draft the intended plain-text transcript before choosing a renderer.
- Load only the reference required for the changed surface.
- Implement semantic output before color, animation, or library-specific controls.
- Test the relevant matrix in verification.md.
- Review the complete before/after transcript, not only edited strings.
Reference Routing
Choose the lowest numbered matching row. Do not combine lower-priority rows after choosing one.
| Priority | Change | Required references |
|---|
| 1 | Prompt, destructive action, or any change affecting both presentation and behavior | All three references |
| 2 | Visual implementation or review with unchanged streams, modes, and contracts | visual-language.md + verification.md |
| 3 | Stream, mode, safety, signal, compatibility, or other behavioral implementation or review with unchanged human presentation | behavior.md + verification.md |
| 4 | Advisory copy or layout draft with no source change | visual-language.md |
Every implementation or review loads verification.md and runs the minimum checks for every applicable profile.
Non-Negotiables
- Design the command journey, not isolated strings.
- Make human output useful without breaking composition and automation.
- Treat interaction, format, decoration, and verbosity as separate axes.
- Ask only for unresolved input; never require a prompt.
- Show meaningful state transitions, but omit phases that add no information.
- Scale confirmation strength to the consequence of the action.
- Print enough for slow work and state changes, but not developer-only detail by default.
- Make errors explain the failure and the safest next action.
- Treat command grammar, streams, exit codes, and machine output as APIs.
- Treat secrets and remote or user-provided text as untrusted data.
- Preserve compatibility over visual consistency for an established public contract.
Completion Check
Before considering a CLI change done, answer:
- What target did the command resolve?
- What will it change?
- What happened?
- What can the user or caller do next?
Filters, machine protocols, live streams, wrappers, CI adapters, and no-op queries may intentionally omit some answers. Do not force workflow output onto them.
Source Basis
This original synthesis is informed by the Command Line Interface Guidelines and Vercel's CLI UX skill. It deliberately does not reuse their product vocabulary, branded glyphs, helper APIs, or command contracts.
