create-cli

jMerta's avatarfrom jMerta

Design command-line interface parameters and UX: arguments, flags, subcommands, help text, output formats, error messages, exit codes, prompts, config/env precedence, and safe/dry-run behavior. Use when you’re designing a CLI spec (before implementation) or refactoring an existing CLI’s surface area for consistency, composability, and discoverability.

⭐90stars🔀6forks📁View on GitHub🕐Updated Jan 2, 2026

When & Why to Use This Skill

This Claude skill facilitates the professional design of command-line interfaces (CLIs) by providing a structured framework for defining syntax, UX, and behavior. It helps developers create consistent, discoverable, and script-friendly CLI specifications—covering arguments, flags, subcommands, and error handling—aligned with industry best practices like clig.dev.

Use Cases

  • 1. New CLI Specification: Rapidly generate a comprehensive technical spec for a new command-line tool, including usage patterns, flag tables, and subcommand hierarchies.
  • 2. Interface Refactoring: Audit and redesign existing CLI surface areas to improve consistency, composability, and user discoverability for legacy tools.
  • 3. Standardizing Engineering Workflows: Establish a unified CLI design language across various internal team projects to ensure a predictable and professional experience for developers.
  • 4. Cross-Platform Behavior Design: Plan robust CLI interactions that handle environment variables, configuration files, and exit codes correctly across macOS, Linux, and Windows.
namecreate-cli
description>
Design command-line interface parameters and UXarguments, flags, subcommands,

Create CLI

Design CLI surface area (syntax + behavior), human-first, script-friendly.

Do This First

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.

Attribution

This skill was copied from steipete/agent-scripts. Upstream: https://github.com/steipete/agent-scripts License: MIT (see LICENSE)