cli-development-guidelines

# CLI Development Guidelines ## When to activate this skill - You are *designing*, *implementing*, or *reviewing* a command-line tool. - The user mentions (explicitly or implicitly): `--help`, flags, subcommands, exit codes, stdout/stderr, piping, JSON output, color, prompts, config files, env vars, “works in CI”, install/uninstall, telemetry. ## What this skill produces - A *CLI contract* (what users can rely on): commands, flags, IO behavior, exit codes, config/env, examples, and safety behavior. - Draft *help output* and docs structure (example-first). - A *compliance audit* (when runnable) using `scripts/cli_audit.py`. ## Non-negotiable CLI citizenship - Exit codes: - `0` on success. - Non-zero on failure (and ideally meaningful, documented codes). - Streams: - `stdout` is for primary output and machine-readable output. - `stderr` is for errors, warnings, progress, and “what I’m doing” messaging. - Discoverability: - `--help` (and usually `-h`) shows help and exits. - `--version` prints version and exits. - Interactivity: - Prompts only when `stdin` is a TTY. - Provide `--no-input` to force non-interactive behavior. - Scripting friendliness: - No ANSI color / spinners when output isn’t a TTY. - Support `NO_COLOR` and `--no-color`. - Consider `--json` and `--plain` for stable output. ## Workflow ### Sketch the CLI contract first - Start from the user’s jobs-to-be-done (what they’re trying to accomplish). - Decide: - Command shape: single command vs subcommands (`noun verb` is common). - Inputs: args vs flags vs stdin vs prompts vs config/env. - Outputs: human default, plus machine modes (`--json`, `--plain`, `--quiet`). - Safety: confirmations, `--dry-run`, `--force`, secret handling. Use: - [CLI reference](references/REFERENCE.md) - [CLI spec template](templates/cli-command-spec-template.json) ### Implement with safe defaults - Use a CLI parsing library (don’t hand-roll). - Make “boundary-crossing” actions explicit: - Network calls - Writing files not explicitly provided - Mutating remote state - Avoid footguns: - Don’t accept secrets via flags or environment variables. - Don’t print stack traces by default. - Don’t assume TTY (detect it). ### Validate and iterate - Run an automated sanity check (when possible): - `python scripts/cli_audit.py -- <your-cli> [subcommand]` - Fix in this order: - Broken stdout/stderr separation - Incorrect exit codes - Help that’s missing or undiscoverable - Unsafe defaults (destructive ops, secrets, hidden network writes) - Unscriptable output (no stable modes) Use: - [Checklist](references/CHECKLIST.md) - `scripts/cli_audit.py` ## Reference library - Core reference: [references/REFERENCE.md](references/REFERENCE.md) - Quick audit checklist: [references/CHECKLIST.md](references/CHECKLIST.md) - Evaluation prompts: [references/EVAL_PROMPTS.md](references/EVAL_PROMPTS.md) ## Templates and scripts - CLI spec template: `templates/cli-command-spec-template.json` - Help text template: `templates/help-text-template.md` - Error message template: `templates/error-message-template.md` - Audit a CLI: `scripts/cli_audit.py`