| name | create-cli |
| description | Design command-line interface parameters and UX: arguments, flags, subcommands, help text, output formats, error messages, exit codes, prompts, config/env precedence, and safe/dry-run behavior. Use when you're designing a CLI spec (before implementation) or refactoring an existing CLI's surface area for consistency, composability, and discoverability.
|
Create CLI
Design CLI surface area (syntax + behavior), human-first, script-friendly.
Do This First
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] <subcommand> [args]
- Subcommands:
mycmd init ...mycmd run ...
- Global flags:
-h, --help--version-q, --quiet / -v, --verbose (define exactly)--json / --plain (if applicable)
- I/O contract:
- Exit codes:
0 success1 generic failure2 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.
