# Designing CLI

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

- Skill: `h3y6e/designing-cli` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add h3y6e/designing-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/h3y6e/designing-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: h3y6e (https://skillmd.com/u/h3y6e)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/h3y6e/designing-cli

---


# Designing CLIs

## Workflow

1. **Start.** For a new CLI, confirm the language and whether it ships as a binary.
2. **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.
   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`.
3. **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.
4. **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.
5. **Done** when every item passes or is n/a and the probe has no FAIL.

## Checklist

### Input

- 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 `--`.
- Bare `app`, `-h`, and `--help` at any level print help to stdout and exit 0.
- `--version` and bare `-v` print the version; `-V` and `version` follow the framework. Only the root parses version flags.
- Prompt only on a TTY, with a flag to skip each prompt.

### Output

- Results go to stdout; messages, progress, and child-process stderr go to stderr.
- List and status commands take `--json`; streamed output is JSONL ending in a result record, even on early failure or cancellation.
- Exit quietly on a closed pipe.
- Color and spinners: `--no-color`, then `CLICOLOR_FORCE`, then `NO_COLOR` / `TERM=dumb` / `CLICOLOR=0`, then TTY detection.
- Tables: one entry per line, no borders.

### Errors

- Errors give a stable code, cause, runnable fix, and docs URL if any, as result-record fields under `--json`; `--quiet` never hides them.
- Unknown commands suggest "did you mean"; usage errors point to `--help`.
- Unexpected errors print a summary and the flag that adds a traceback and debug log. Log files are timestamped, truncated, and ANSI-free.
- Exit 0 on success, help, and version; 1 on failure; 2 on usage errors. Help documents other codes.
- On SIGINT or SIGTERM, cancel remote work, clean up, and re-raise the signal.

### Safety

- Each command's effect is `read`, `write`, or `destructive`; help marks destructive ones.
- Destructive commands show what will be deleted, overwritten, or sent, then confirm on a TTY; without `--yes`, exit 2 and suggest `--dry-run`.
- Write and destructive commands take `--dry-run`.
- Secrets never arrive as arguments or env vars.

### Files and release

- Separate XDG directories for config, state, data, and cache. With config files, follow [references/config.md](references/config.md).
- When a binary ships, follow [references/distribution.md](references/distribution.md).
- With a TUI or an agent hook, follow [references/situational.md](references/situational.md).

### Speed and compatibility

- Start in 100–500ms, loading only the invoked command.
- No network at startup unless the command needs it; update checks never block and can be disabled.
- Gate unstable features behind an `experimental` setting.
- Version data and wire formats, `--json` included, apart from the CLI; removing, renaming, or retyping a field is breaking.
- For a background process, follow [references/daemon.md](references/daemon.md).

