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.
• •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).
• •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.