/sota-cli-ux

name: sota-cli-ux
description: >-
  State-of-the-art CLI and developer-tool UX guidance (2026) covering command
  and flag design, output and interaction (stdout/stderr, --json, TTY
  detection, exit codes, prompts), runtime behavior and lifecycle (signals,
  dry-run, idempotency, XDG paths, completions, telemetry), and distribution
  (packaging, checksums, docs). Use when designing or building any command
  line tool, subcommand, TUI, or developer tool — in any framework (argparse,
  click, typer, clap, cobra, oclif, commander) — AND when auditing an existing
  CLI for usability, scriptability, and compatibility. Not for shell-script
  correctness or security — use sota-shell-scripting. Trigger keywords: CLI,
  command line tool, flags, subcommands, terminal output, TUI, developer tool,
  argparse, clap, cobra, exit code, shell completion, man page, stdin, stdout.

SOTA CLI & Developer-Tool UX

Purpose

Expert-level rules for building and auditing command-line tools: the grammar of commands/flags/args, config layering, human-vs-machine output, TTY-aware interaction, exit codes, signal handling, lifecycle behavior, and distribution. The core thesis: **a CLI has three users — a human at a TTY, a script in CI, and an AI agent driving the tool (a stricter script) — and every design decision must serve all three without flags-gymnastics.** Rules are imperative with rationale and good/bad terminal examples; every rules file ends with an audit checklist. Load only the files relevant to the task via the index below.

BUILD mode

When designing or implementing a CLI:

1. **Design the command grammar before writing code.** Write the `--help` text first: subcommand tree, every flag (short + long), args, examples. If the help is hard to write, the grammar is wrong (`rules/01`). 2. **Defaults carry the common path.** A new user must get a useful result with zero flags. Anything required for the 80% case is a design bug (`rules/01` §3). 3. **Split the streams from day one**: primary output → stdout, everything else (logs, progress, prompts, errors) → stderr. Retrofitting this breaks users' pipes (`rules/02` §1). 4. **Make it pipe-safe by default**: detect TTY; disable color/progress/prompts when piped; honor `NO_COLOR`; ship `--json` with every listing/reading command from v0.1, because output format is API (`rules/02`). 5. **Treat exit codes, flags, env vars, and JSON shapes as a public API**: document them, version them, deprecate — never repurpose or remove without a cycle (`rules/02` §3, `rules/03` §7). 6. **Build the unhappy paths with the happy path**: Ctrl-C cleanup, `--dry-run` on mutating commands, re-runnable/resumable operations, stdin-closed CI behavior, offline behavior (`rules/03`). 7. **Plan distribution early**: single static binary if the ecosystem allows, checksums + signatures, completions and man page generated from the same source as `--help` (`rules/03` §8, `rules/04`). 8. Before declaring done, run every relevant **Audit checklist** against your own tool, including the brutal smoke test: `tool cmd | cat`, `tool cmd > out.txt 2> err.txt`, `tool cmd < /dev/null`, `echo $?`.

AUDIT mode

When reviewing an existing CLI:

1. Identify the surface: parser setup (argparse/clap/cobra/etc.), main/entry point, output and error paths, signal handlers, config loading, install/ release scripts. Load the matching rules files. 2. **Run the tool, don't just read it.** Minimum probe set:

• `tool --help`, `tool <sub> -h`, `tool --version`, `tool definitelynotacmd`
• `tool list | cat` and `tool list | head -1` (color codes? broken pipe panic?)
• `tool list > /dev/null` — does anything still reach the human? (it should, on stderr)
• `tool mutate < /dev/null` — hang waiting for a prompt = CI killer
• `echo $?` after success, after a usage error, after a real failure
• Ctrl-C mid-operation: prompt state restored? partial state cleaned or resumable?

3. Then verify in code what can't be probed: config precedence order, secret handling, temp/state file locations, update/telemetry behavior.

Severity conventions

• **Critical** — corrupts data or destroys trust: destructive op with no

confirmation/`--force` and no dry-run; non-zero work reported as exit 0 (or vice versa) so CI lies; prompt hangs forever with stdin closed; secrets echoed to terminal/logs/argv; auto-update or telemetry without disclosure.

• **High** — breaks scripting or interrupts users: machine output polluted by

ANSI codes/log lines on stdout; no `--json` on listing commands; SIGINT leaves corrupt partial state; undocumented/colliding exit codes; config precedence nondeterministic; breaking flag removal without deprecation.

• **Medium** — erodes usability: missing long forms; required flags on common

path; no progress on >2s ops; errors without remediation; `$HOME` dotfile litter instead of XDG; no completions; no `-q`/`-v`; >500ms `--help`.

• **Low** — polish: help without examples, no suggest-on-typo, inconsistent

subcommand naming, missing man page, table borders in output.

Finding format

[SEVERITY] <one-line title>
Where: <file:line | command invocation that reproduces it>
Rule: <rules-file §section>
Issue: <what is wrong, with observed evidence (transcript or code)>
Impact: <who breaks: the human at the TTY, the script in CI, an agent driving the tool, or all>
Fix: <specific change; exact flag/stream/exit-code where load-bearing>

Order findings by severity; one finding per root cause; include the reproducing command line whenever the issue was observed by running the tool.

Rules index

| File | Read this when... | |---|---| | `rules/01-commands-flags-config.md` | Designing/auditing the command surface: subcommand grammar (noun-verb consistency), POSIX/GNU flag conventions, short/long forms, `--` separator, args vs flags vs stdin, defaults, dangerous-op flags, config precedence chain, env var naming, he