cli-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```text
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.

From caarlos0/dotfiles, MIT.

More from caarlos0/dotfiles