create-cli

# Create CLI Design CLI surface area (syntax + behavior), human-first, script-friendly. ## Do This First - Read `agent-scripts/skills/create-cli/references/cli-guidelines.md` and apply it as the default rubric. - Upstream/full guidelines: https://clig.dev/ (propose changes: https://github.com/cli-guidelines/cli-guidelines) - Ask only the minimum clarifying questions needed to lock the interface. ## Clarify (fast) Ask, then proceed with best-guess defaults if user is unsure: - Command name + one-sentence purpose. - Primary user: humans, scripts, or both. - Input sources: args vs stdin; files vs URLs; secrets (never via flags). - Output contract: human text, `--json`, `--plain`, exit codes. - Interactivity: prompts allowed? need `--no-input`? confirmations for destructive ops? - Config model: flags/env/config-file; precedence; XDG vs repo-local. - Platform/runtime constraints: macOS/Linux/Windows; single binary vs runtime. ## Deliverables (what to output) When designing a CLI, produce a compact spec the user can implement: - Command tree + USAGE synopsis. - Args/flags table (types, defaults, required/optional, examples). - Subcommand semantics (what each does; idempotence; state changes). - Output rules: stdout vs stderr; TTY detection; `--json`/`--plain`; `--quiet`/`--verbose`. - Error + exit code map (top failure modes). - Safety rules: `--dry-run`, confirmations, `--force`, `--no-input`. - Config/env rules + precedence (flags > env > project config > user config > system). - Shell completion story (if relevant): install/discoverability; generation command or bundled scripts. - 5–10 example invocations (common flows; include piped/stdin examples). ## Default Conventions (unless user says otherwise) - `-h/--help` always shows help and ignores other args. - `--version` prints version to stdout. - Primary data to stdout; diagnostics/errors to stderr. - Add `--json` for machine output; consider `--plain` for stable line-based text. - Prompts only when stdin is a TTY; `--no-input` disables prompts. - Destructive operations: interactive confirmation + non-interactive requires `--force` or explicit `--confirm=...`. - Respect `NO_COLOR`, `TERM=dumb`; provide `--no-color`. - Handle Ctrl-C: exit fast; bounded cleanup; be crash-only when possible. ## Templates (copy into your answer) ### CLI spec skeleton Fill these sections, drop anything irrelevant: 1. **Name**: `mycmd` 2. **One-liner**: `...` 3. **USAGE**: - `mycmd [global flags] <subcommand> [args]` 4. **Subcommands**: - `mycmd init ...` - `mycmd run ...` 5. **Global flags**: - `-h, --help` - `--version` - `-q, --quiet` / `-v, --verbose` (define exactly) - `--json` / `--plain` (if applicable) 6. **I/O contract**: - stdout: - stderr: 7. **Exit codes**: - `0` success - `1` generic failure - `2` invalid usage (parse/validation) - (add command-specific codes only when actually useful) 8. **Env/config**: - env vars: - config file path + precedence: 9. **Examples**: - … ## Notes - Prefer recommending a parsing library (language-specific) only when asked; otherwise keep this skill language-agnostic. - If the request is “design parameters”, do not drift into implementation.