CLI Design

CLI Design

Treat a CLI as both a human interface and a stable automation API. Follow repository instructions and existing command conventions before introducing a new grammar, output format, exit status, or configuration mechanism.

Define the contract first

Before implementation, identify separately:

1. The human workflows: discovery, common use, mistakes, recovery, and advanced use.
2. The automation workflows: unattended execution, input, output parsing, failure handling, and composition with other tools.
3. The public contract: commands, options, operands, defaults, streams, exit statuses, prompts, environment variables, configuration, and structured output.

Write representative invocations before choosing a parser or framework:

tool [global-options] <command> [command-options] [operands]

Use noun/verb subcommands when they fit the domain, but preserve an established project grammar. Prefer a shallow, regular hierarchy over many special cases.

Design predictable commands

• Give commands and long options lowercase, descriptive, spellable names.
• Use commands for actions and options for parameters or behavior modifiers.
• Keep the same concept named and spelled consistently across commands.
• Reserve short options for frequent operations and provide a descriptive long equivalent. Do not assign every option a short form.
• Prefer explicit options over ambiguous positional arguments. Use positional operands when their meaning and order are obvious.
• Support -- before operands so names beginning with - remain addressable.
• Where file operands make sense, consider - as stdin or stdout and document the exact behavior.
• Decide whether options may appear after operands, whether short options may be grouped, and how optional values parse. Document and test the decision.
• Do not accept arbitrary command abbreviations. Suggest likely corrections, but never silently execute a guessed command.
• Treat aliases as compatibility interfaces. Add one only when it is worth supporting for the lifetime of the CLI.
• Avoid implicit catch-all behavior that turns a typo into another valid, potentially destructive operation.

Familiar options such as --help, --version, --quiet, --verbose, --output, --json, --color, --no-input, and --dry-run should retain their conventional meaning.

Make help useful at the point of failure

• Provide -h and --help at every command level unless an established compatibility contract prevents it.
• Help must exit successfully without performing normal work, loading remote data, or requiring valid credentials or configuration.
• Order help for scanning: purpose, usage, common examples, common options, remaining options or commands, then further documentation.
• Lead with realistic examples, including piped or unattended use where relevant.
• Show defaults, accepted values, units, repetition rules, conflicts, and whether an option can be supplied through configuration or environment.
• For invalid input, explain the specific problem and show only the relevant usage or hint. Do not print the entire manual after every typo.
• Distinguish parse errors from operational failures.
• For large CLIs, keep default help concise and provide a full-help or reference tier.
• Generate help, shell completion, and reference documentation from the same command model where practical so they cannot drift.

Completion must tolerate incomplete input and must be fast, non-interactive, side-effect-free, and safe when configuration, credentials, or the network are unavailable. Avoid remote completion unless it is explicitly bounded and has a local fallback.

Keep the stream contract strict

• Write requested result data to stdout.
• Write diagnostics, warnings, prompts, progress, and debug information to stderr.
• Do not write headings, notices, progress, or ANSI control sequences into machine-readable stdout.
• Assert stdout, stderr, and exit status independently in tests.
• Keep --quiet limited to nonessential messaging. It must not change result semantics, suppress required errors, or turn failure into success.
• Send verbose or debug diagnostics to stderr and redact secrets.

Human-readable tables and prose may evolve for usability. Do not require scripts to parse them. When automation is expected, provide an explicit stable format such as:

• JSON for one bounded result;
• JSON Lines for streamed records or events;
• plain delimited fields where JSON is excessive;
• templates or field selection for user-controlled rendering;
• NUL-delimited output when values may contain whitespace or newlines.

Document machine-output fields, types, nullability, encoding, framing, ordering, and compatibility policy. If ordering is not guaranteed, say so. Human and machine renderers should consume the same application result rather than implementing behavior separately.

Define exit behavior deliberately

Return zero only for documented success. Use a small, stable, documented set of nonzero statuses rather than exposing arbitrary internal errors.

Decide explicitly how the command reports:

• invalid usage;
• operational failure;
• authentication or authorization failure;
• missing resources;
• empty or no-match results;
• cancellation or interruption;
• partial success;
• accepted or pending asynchronous work.

Do not let partial success look like full success. Report completed and failed items separately and choose an exit status that allows automation to detect the failure.

Follow established shell conventions where applicable, but do not invent portable meaning for every numeric status. Document the statuses that callers are expected to branch on.

Handle broken pipes as normal pipeline termination when the platform and command semantics permit it. Do not replace useful output with a stack trace because a downstream command stopped reading.

Write actionable errors

Expected user-facing failures should answer:

1. What failed?
2. Why did it fail?
3. What can the user do next?

Use domain language rather than parser, transport, or stack internals. Include the relevant resource, option, configuration source, or rejected value without revealing secrets.

• Put the primary error first and actionable hints afterward.
• Name the exact replacement option or command when suggesting a fix.
• Show concise contextual usage for usage errors.
• Preserve the underlying cause for debugging without dumping a stack trace by default.
• Group repeated failures when one explanation applies to many items.
• Never catch an error merely to return success-shaped output or an empty result.

Represent errors structurally inside the application, with a stable category or code, user message, optional hints, underlying cause, and exit status. Render them only at the process boundary.

Keep TTY behavior presentational

Detect stdin, stdout, and stderr independently. They may point to different kinds of destinations.

TTY state may control:

• color and styling;
• paging;
• wrapping and headings;
• buffering;
• progress animation;
• whether prompting is possible.

TTY state must not silently change the selected resources, operation, result schema, or other command semantics.

• Disable cursor motion, animation, and paging when their output stream is not a terminal unless explicitly forced.
• Never prompt unless both input and prompt output are usable terminals.
• Keep redirected and CI output linear and stable.
• Support NO_COLOR, TERM=dumb, and an explicit color mode such as --color=auto|always|never.
• Never encode meaning with color alone. Pair it with text, symbols, or structure.
• Sanitize untrusted terminal control sequences before displaying external data.
• Restore terminal state after cancellation and failure.

Use a pager only for long human-readable output, only when appropriate for the output destination, and provide a way to disable it. Do not page structured output.

Make interactivity optional

Every prompt must have a complete unattended equivalent through an option, operand, stdin, configuration, or environment variable.

• Provide --no-input or an equivalent control when commands might prompt.
• In non-interactive mode, fail immediately and name the missing input and its replacement option.
• Display prompt defaults explicitly. Destructive choices should default to the safe answer.
• Do not infer consent merely because stdin is closed or output is redirected.
• Keep prompt wording, accepted answers, and cancellation behavior consistent.
• Treat Ctrl-C as cancellation: stop starting new work, restore terminal state, and return the documented cancellation status.

Do not make a full-screen or interactive selector the only route to an operation. Share application logic between interactive and non-interactive adapters. Use tui-design when the task specifically involves a full-screen terminal interface.