cli-design

# CLI Design Design a command-line tool's interface before implementation: human-first, script-friendly, Linux-only. Output is a compact spec the user or an agent can implement directly. Rubric source: clig.dev (rebuilt as `references/clig-checklist.md`). ## Workflow ### Phase 1: SCOPE Lock the interface with the minimum questions. Proceed with the conventions in Phase 2 when the user is unsure. - Command name and one-sentence purpose. - Primary user: humans, scripts, or both. - Input sources: args vs stdin; files vs URLs. Secrets travel via file or stdin, because flags leak through `ps` and shell history. - Output contract: human text, `--json`, `--plain`, exit codes. - Interactivity: prompts allowed? `--no-input` needed? confirmation for destructive ops? - Config model: flags, env, config file; precedence. **Gate:** name, purpose, and I/O contract are known. Proceed only when gate passes. ### Phase 2: DESIGN Load [references/clig-checklist.md](references/clig-checklist.md) and apply it as the default rubric. For each section, pick the convention and record it in the spec. Diverge from a convention only deliberately, and document the divergence in the spec — interfaces are contracts, and surprising contracts break scripts. ### Phase 3: DELIVER Produce the spec from this skeleton. Drop a section only when it genuinely has no content; fill every other section. 1. **Name and one-liner**: command name plus a single sentence of purpose 2. **Usage line**: the synopsis a...