1---2name: designing-cli3description: Designs CLIs that humans, scripts, and agents drive predictably. Use when creating a CLI, or adding or changing its commands, flags, output, errors, config, background process, or release.4compatibility: Requires Node.js, and the usage CLI to probe with a spec.5license: MIT6metadata:7 source: https://skillmd.com/skills/h3y6e/designing-cli8 author: h3y6e9 version: 2026.11.210---1112# Designing CLIs1314## Workflow15161. **Start.** For a new CLI, confirm the language and whether it ships as a binary.172. **Define** commands, flags, help, examples, and effects in one framework definition: cobra and `github.com/jdx/usage/integrations/cobra` for Go, adding viper only with config files; gunshi v1 with `@gunshi/plugin-suggestion`, `@h3y6e/gunshi-plugin-env`, and `@h3y6e/gunshi-plugin-usage` for TypeScript; usage-rs for Rust; usage `#USAGE` comments for shell.18 For Go, also invoke the `golang-cli` and `golang-spf13-cobra` skills, plus `golang-spf13-viper` once viper is added; if they are not installed, ask the user to add them from `samber/cc-skills-golang`.193. **Classify** each item below as pass, n/a, or deviation in a table, citing a probe line, command run, or code read. Items without a subject are n/a. Fix every deviation; [references/rationale.md](references/rationale.md) gives the reasons.204. **Probe**: build, then run `scripts/probe.mjs <bin> [app.usage.kdl]`, passing the spec when the framework exports one. Fix each FAIL; NOTEs are evidence.215. **Done** when every item passes or is n/a and the probe has no FAIL.2223## Checklist2425### Input2627- Subcommands nest with spaces in one consistent order (`app server start`). Positionals name the target, one kind at most; flags are optional and also read `APP_*` env vars; child-process arguments follow `--`.28- Bare `app`, `-h`, and `--help` at any level print help to stdout and exit 0.29- `--version` and bare `-v` print the version; `-V` and `version` follow the framework. Only the root parses version flags.30- Prompt only on a TTY, with a flag to skip each prompt.3132### Output3334- Results go to stdout; messages, progress, and child-process stderr go to stderr.35- List and status commands take `--json`; streamed output is JSONL ending in a result record, even on early failure or cancellation.36- Exit quietly on a closed pipe.37- Color and spinners: `--no-color`, then `CLICOLOR_FORCE`, then `NO_COLOR` / `TERM=dumb` / `CLICOLOR=0`, then TTY detection.38- Tables: one entry per line, no borders.3940### Errors4142- Errors give a stable code, cause, runnable fix, and docs URL if any, as result-record fields under `--json`; `--quiet` never hides them.43- Unknown commands suggest "did you mean"; usage errors point to `--help`.44- Unexpected errors print a summary and the flag that adds a traceback and debug log. Log files are timestamped, truncated, and ANSI-free.45- Exit 0 on success, help, and version; 1 on failure; 2 on usage errors. Help documents other codes.46- On SIGINT or SIGTERM, cancel remote work, clean up, and re-raise the signal.4748### Safety4950- Each command's effect is `read`, `write`, or `destructive`; help marks destructive ones.51- Destructive commands show what will be deleted, overwritten, or sent, then confirm on a TTY; without `--yes`, exit 2 and suggest `--dry-run`.52- Write and destructive commands take `--dry-run`.53- Secrets never arrive as arguments or env vars.5455### Files and release5657- Separate XDG directories for config, state, data, and cache. With config files, follow [references/config.md](references/config.md).58- When a binary ships, follow [references/distribution.md](references/distribution.md).59- With a TUI or an agent hook, follow [references/situational.md](references/situational.md).6061### Speed and compatibility6263- Start in 100–500ms, loading only the invoked command.64- No network at startup unless the command needs it; update checks never block and can be disabled.65- Gate unstable features behind an `experimental` setting.66- Version data and wire formats, `--json` included, apart from the CLI; removing, renaming, or retyping a field is breaking.67- For a background process, follow [references/daemon.md](references/daemon.md).