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]

1. Subcommands:

- mycmd init ... - mycmd run ...

1. Global flags:

- -h, --help - --version - -q, --quiet / -v, --verbose (define exactly) - --json / --plain (if applicable)

1. I/O contract:

- stdout: - stderr:

1. Exit codes:

- 0 success - 1 generic failure - 2 invalid usage (parse/validation) - (add command-specific codes only when actually useful)

1. Env/config:

- env vars: - config file path + precedence:

1. Examples:

- ...

Notes

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