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.
• Upstream/full guidelines: https://clig.dev/ (propose changes: https://github.com/cli-guidelines/cli-guidelines)
• 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).
• Shell completion story (if relevant): install/discoverability; generation command or bundled scripts.
• 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.