cli-development-guidelines

Design and review command-line interfaces (CLI tools) with human-first UX and UNIX composability: arguments/flags, help text, stdout/stderr, exit codes, interactivity, configuration, errors, telemetry, and distribution.

⭐4stars🔀0forks📁View on GitHub🕐Updated Dec 31, 2025

When & Why to Use This Skill

This Claude skill provides professional-grade guidelines and frameworks for designing, implementing, and reviewing Command-Line Interfaces (CLI). It focuses on human-first UX and UNIX composability, ensuring tools follow industry standards for exit codes, stream management (stdout/stderr), discoverability, and scripting friendliness to create robust, developer-centric utilities.

Use Cases

  • Designing a robust CLI contract including subcommands, flags, and arguments for a new software project to ensure a consistent user experience.
  • Conducting a compliance audit on existing CLI tools to fix broken stdout/stderr separation and ensure meaningful exit codes.
  • Implementing 'scripting-friendly' features such as JSON output modes and NO_COLOR support for seamless integration into CI/CD pipelines.
  • Generating standardized help documentation and interactive prompts that automatically detect TTY status to prevent hanging in non-interactive environments.
  • Reviewing CLI security and safety defaults, such as implementing --dry-run modes and preventing the accidental exposure of secrets via flags.
namecli-development-guidelines
descriptionThis skill should be used when designing, implementing, or reviewing CLI tools, or when flags, subcommands, help text, exit codes, or `--cli-dev` are mentioned.
licenseCC-BY-SA-4.0 (docs, adapted from clig.dev); MIT (scripts)
compatibilityScripts use Python 3.10+ (scripts/cli_audit.py).
version"0.1.0"
upstream"clig.dev + POSIX/GNU/Heroku/12-factor + Agent Skills spec"

CLI Development Guidelines

When to activate this skill

  • You are designing, implementing, or reviewing a command-line tool.
  • The user mentions (explicitly or implicitly): --help, flags, subcommands, exit codes, stdout/stderr, piping, JSON output, color, prompts, config files, env vars, “works in CI”, install/uninstall, telemetry.

What this skill produces

  • A CLI contract (what users can rely on): commands, flags, IO behavior, exit codes, config/env, examples, and safety behavior.
  • Draft help output and docs structure (example-first).
  • A compliance audit (when runnable) using scripts/cli_audit.py.

Non-negotiable CLI citizenship

  • Exit codes:
    • 0 on success.
    • Non-zero on failure (and ideally meaningful, documented codes).
  • Streams:
    • stdout is for primary output and machine-readable output.
    • stderr is for errors, warnings, progress, and “what I’m doing” messaging.
  • Discoverability:
    • --help (and usually -h) shows help and exits.
    • --version prints version and exits.
  • Interactivity:
    • Prompts only when stdin is a TTY.
    • Provide --no-input to force non-interactive behavior.
  • Scripting friendliness:
    • No ANSI color / spinners when output isn’t a TTY.
    • Support NO_COLOR and --no-color.
    • Consider --json and --plain for stable output.

Workflow

Sketch the CLI contract first

  • Start from the user’s jobs-to-be-done (what they’re trying to accomplish).
  • Decide:
    • Command shape: single command vs subcommands (noun verb is common).
    • Inputs: args vs flags vs stdin vs prompts vs config/env.
    • Outputs: human default, plus machine modes (--json, --plain, --quiet).
    • Safety: confirmations, --dry-run, --force, secret handling.

Use:

Implement with safe defaults

  • Use a CLI parsing library (don’t hand-roll).
  • Make “boundary-crossing” actions explicit:
    • Network calls
    • Writing files not explicitly provided
    • Mutating remote state
  • Avoid footguns:
    • Don’t accept secrets via flags or environment variables.
    • Don’t print stack traces by default.
    • Don’t assume TTY (detect it).

Validate and iterate

  • Run an automated sanity check (when possible):
    • python scripts/cli_audit.py -- <your-cli> [subcommand]
  • Fix in this order:
    • Broken stdout/stderr separation
    • Incorrect exit codes
    • Help that’s missing or undiscoverable
    • Unsafe defaults (destructive ops, secrets, hidden network writes)
    • Unscriptable output (no stable modes)

Use:

Reference library

Templates and scripts

  • CLI spec template: templates/cli-command-spec-template.json
  • Help text template: templates/help-text-template.md
  • Error message template: templates/error-message-template.md
  • Audit a CLI: scripts/cli_audit.py