gupsammy/create-cli

Create CLI

Design CLI surface area (syntax + behavior), agent-aware, human-friendly.

Phase 1 — Prepare

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/cli-guidelines.md. Apply it as the default CLI rubric, including the Agent Ergonomics section.

For new CLI designs, also read ${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/language-selection.md to inform the language recommendation in Phase 2. Skip it for audits — the language is already chosen.

Proceed when cli-guidelines.md is loaded.

Phase 2 — Clarify

Determine whether this is a new design or an audit from the user's trigger.

New design

Ask, then proceed with best-guess defaults if user is unsure:

• Command name + one-sentence purpose.
• Primary consumer: agent/LLM, human at a terminal, scripted automation, or mixed.
• Input sources: args vs stdin; files vs URLs; secrets (never via flags).
• Output contract: human text by default, --json for structured output, exit codes.
• Interactivity: prompts allowed? need --no-input? confirmations for destructive ops?
• Config model: flags/env/config-file; precedence; XDG vs repo-local.
• Language & distribution: ask for the user's preferred implementation language, or offer to recommend one. Ask whether a single binary (no runtime needed on target machine) is required, or whether a runtime dependency is acceptable. Apply language-selection.md to recommend if the user is unsure. Platform: macOS/Linux/Windows.

If an existing CLI spec or tool description is provided, read it first — skip questions already answered by it.

Audit

Ask:

• CLI name and source location (repo path, or provide --help output).
• Primary consumer: agent, human, or mixed.
• Known pain points or specific areas to focus on.

Then explore the codebase: use Glob/Grep to find command definitions, flag registrations, output formatting, and error handling. Run <cli> --help via Bash to capture actual behavior.

Proceed when answers are confirmed or user is unsure — use best-guess defaults.

Phase 3 — Conventions

Apply the conventions from cli-guidelines.md (loaded in Phase 1), including the Agent Ergonomics section. The rules below are the key conventions to enforce — cli-guidelines.md provides the full rubric for edge cases.

If primary consumer is human-only, the Errors and Reduce Tool Calls subsections are optional — apply them only if the user wants script-friendliness.

Output

• Default output is human-readable text. --json gives structured JSON. Explicit is better than implicit — no TTY sniffing, no surprises.
• List commands in --json mode use NDJSON (one JSON object per line) — enables streaming and jq piping without buffering. For paginated results with metadata, a JSON object with an items array is acceptable. If the CLI extends an existing ecosystem that uses JSON arrays (kubectl, aws, gh), match the ecosystem convention.
• Primary data to stdout; diagnostics/errors to stderr.
• Suppress ANSI codes, progress spinners, and decorative output when --json is passed or when stdout is not a TTY.

Errors (agent/mixed consumers only)

• When --json is active, emit error objects on stderr: {"error": "<snake_case_code>", "message": "...", "hint": "<exact CLI invocation or null>"} — so agent callers can route recovery logic without parsing free-text stderr. The hint field must be an executable command, not prose.
• Exit codes: 0 success, 1 runtime error, 2 invalid usage; add command-specific codes only when genuinely useful.

Flags

• -h/--help always shows help; ignores other args.
• --version prints version to stdout.
• --json preferred for structured output. --output json/-o json acceptable when the CLI needs multiple output formats (yaml, table, csv) under a single flag. Pick one and apply consistently.
• Consistent flag names across all subcommands for the same concept (--id, --force, --json) — agents learn the naming pattern once and apply it everywhere without guessing.
• Prompts only when stdin is a TTY; --no-input disables prompts. --non-interactive acceptable if the ecosystem already uses it.
• Destructive operations: interactive confirmation; non-interactive requires --force.
• Respect NO_COLOR, TERM=dumb; provide --no-color.
• Handle Ctrl-C: exit fast; bounded cleanup; crash-only when possible.

Reduce Tool Calls (agent/mixed consumers only)

• Compound output: operations return enough data to avoid a follow-up call. create returns the new resource's ID and key fields. delete echoes what was removed.
• Rich JSON defaults: in --json mode, return full objects not just IDs.
• Bounded lists: list commands default to a safe limit (e.g., 50 items) with --limit to adjust. In JSON mode, include has_more (bool) and optionally next_cursor for keyset pagination. Unbounded output wastes tokens and risks context overflow for agent callers.
• Idempotent by default: where possible, commands are safe to repeat; document preconditions explicitly — agents rely on safe retries for error recovery without human intervention.

Apply all applicable conventions, then proceed to Phase 4.

Phase 4 — Deliver

Audits

Evaluate the existing CLI against every Phase 3 subsection. For each convention, state: what the CLI does today, whether it conforms, and what to change. Also check:

• Flag naming consistency across subcommands.
• Help text quality (examples present, common flags first, fits one screen).
• Config precedence (flags > env > project config > user config > defaults).
• Destructive-op safety (confirmations, --force, --dry-run).
• Shell completion availability.

Produce a gap report organized by severity: Breaking (requires API change), Major (agent-breaking or convention violation), Minor (cosmetic/polish). Each finding: current behavior, convention violated, recommended fix with migration risk (none/low/breaking).

New designs

Produce a compact spec the user can implement. Include all relevant sections:

• 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; --json for structured output; --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).

Use this skeleton, dropping irrelevant sections:

0. Language & distribution: Go · cobra · single binary · goreleaser for CI (Omit if language was not determined.)
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 (structured JSON output; NDJSON for list commands)
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:
   • …

See ${CLAUDE_PLUGIN_ROOT}/skills/create-cli/examples/example-cli-spec.md for a complete worked example.

If the spec is destined for a skill body or CLAUDE.md, omit unused sections entirely (do not mark them "N/A") and limit examples to ≤5 invocations that each demonstrate multiple patterns.

Phase 5 — Verify

For new specs: confirm the spec covers all applicable sections from the Phase 4 skeleton. Verify the examples section demonstrates at least: --json output, error recovery (if agent/mixed consumer), and one piped/stdin usage.

For audits: confirm the gap report addresses every Phase 3 subsection and includes at least one example invocation showing the recommended fix for each Major finding.

Skill is complete when verification passes.

Notes

• Once language is selected (Phase 2), include the idiomatic parsing library in the spec (see language-selection.md). If language remains undetermined, omit the library.
• If the request is "design parameters", do not drift into implementation.