Create CLI Tool

Create CLI Tool

Shape a CLI that feels good for people and predictable for scripts.

Start Here

• Read references/cli-guidelines.md and treat it as the default rubric.
• Consider upstream guidance at https://clig.dev/ when resolving tradeoffs.
• Ask only the minimum questions needed to lock the interface.
• Design forward only. Do not preserve legacy behavior unless the user asks.

Quick Clarify

Ask, then proceed with sensible defaults if unclear:

• Command name and single-sentence purpose.
• Primary audience: humans, scripts, or both.
• Inputs: flags/args vs stdin; files vs URLs; secrets never via flags.
• Outputs: human text, structured (--json), or stable line text (--plain).
• Interactivity: prompts allowed; need --no-input; confirmations for destructive ops.
• Configuration: flags vs env vs config file; precedence model; XDG vs repo-local.
• Runtime constraints: OS targets; single binary or runtime required.

What to Deliver

Produce a compact, implementation-ready spec:

• Command tree plus USAGE synopsis.
• Full args/flags table: type, default, required, examples.
• Subcommand behavior: inputs, outputs, side effects, idempotence.
• Output rules: stdout vs stderr, TTY detection, --json/--plain, --quiet/--verbose.
• Error taxonomy and exit codes for common failures.
• Safety controls: --dry-run, confirmations, --force, --no-input.
• Config/env rules and precedence (flags > env > project config > user config > system).
• Shell completion approach if relevant.
• 5-10 example invocations, including stdin/pipes.

Defaults Unless Overridden

• -h/--help prints help and ignores other flags.
• --version prints to stdout.
• Primary data to stdout; diagnostics to stderr.
• Provide --json for machine output; add --plain for stable line output when useful.
• Prompt only if stdin is a TTY; --no-input disables prompts.
• Destructive operations require explicit confirmation or --force for non-interactive runs.
• Respect NO_COLOR and TERM=dumb; provide --no-color.
• Handle Ctrl-C with fast exit and minimal cleanup.

Spec Template

Fill only what applies:

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

• Keep it language-agnostic unless asked to recommend a parser library.
• If the request is only about parameters, avoid implementation details.