Introduction
# 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.