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:

Name: mycmd One-liner: ... USAGE: mycmd [global flags] [args] Subcommands: mycmd init ... mycmd run ... Global flags: -h, --help --version -q, --quiet / -v, --verbose (define exactly) --json / --plain (if applicable) I/O contract: stdout: stderr: Exit codes: 0 success 1 generic failure 2 invalid usage (parse/validation) (add command-specific codes only when actually useful) Env/config: env vars: config file path + precedence: 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.