sota-cli-uxlisted

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.
martinholovsky/SOTA-skills · ★ 8 · AI & Automation · score 75

Install: claude install-skill martinholovsky/SOTA-skills

# 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`).