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:

Language & distribution:
```
Go
```
·
```
cobra
```
· single binary ·
```
goreleaser
```
for CI (Omit if language was not determined.)
Name:
```
mycmd
```
One-liner:
```
...
```

USAGE:

mycmd [global flags] <subcommand> [args]

Subcommands:
- ```
mycmd init ...
```
- ```
mycmd run ...
```
Global flags:
- ```
-h, --help
```
- ```
--version
```
- ```
-q, --quiet
```
  /
```
-v, --verbose
```
  (define exactly)
- ```
--json
```
  (structured JSON output; NDJSON for list commands)
I/O contract:
- stdout:
- stderr:
Exit codes:
- ```
0
```
  success
- ```
1
```
  generic failure
- ```
2
```
  invalid usage (parse/validation)
- (add command-specific codes only when actually useful)
Env/config:
- env vars:
- config file path + precedence:
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.

create-cli

NPX Install

Tags

SKILL.md Content