/cli-guideline

name: cli-guideline
description: Implement CLI tools in Python, JS/TS, Bash, or Go following clig.dev standards. Use when writing or reviewing CLI code.

Skill: CLI Guideline

Modern CLI design principles based on [clig.dev](https://clig.dev/) — human-first design while maintaining composability.

Core Philosophy

1. **Human-first design** — CLIs are for humans, not just scripts 2. **Simple parts that work together** — Composable via pipes, stdin/stdout, exit codes 3. **Consistency** — Follow established conventions (flags, env vars, behavior) 4. **Say just enough** — Not too verbose, not too silent 5. **Ease of discovery** — Help, examples, suggestions 6. **Conversation as norm** — Trial-and-error is expected; guide the user 7. **Robustness** — Handle errors gracefully, feel solid 8. **Empathy** — Delight users, exceed expectations

Essential Rules

I/O Streams

| Stream | Purpose | Example | | --------- | -------------------------------------- | -------------------------- | | `stdout` | Primary output, data, machine-readable | Results, JSON, piped data | | `stderr` | Messages, logs, progress, errors | Status, warnings, spinners | | Exit `0` | Success | | | Exit `≠0` | Failure (map codes to failure modes) | |

Help

• `-h` and `--help` show full help (exit 0, ignore other flags)
• No args + required args → concise help (description + 1-2 examples + "use --help")
• Lead with examples, not option lists
• Include support path (URL, issue tracker)
• Suggest likely fixes on typos ("Did you mean...?")
• If expecting stdin and it's a TTY, show help immediately (don't hang)

Output

• Human-readable by default; detect TTY for formatting
• `--plain` for stable, line-based output (scripts, grep/awk)
• `--json` for structured output
• Brief success messages; verbose only when state changes
• Suggest next commands in workflows
• Color: intentional (not decorative); disable via `NO_COLOR`, `TERM=dumb`, `--no-color`
• No animations/spinners when stdout is not TTY
• No debug noise by default; use `--debug` or `DEBUG=1`

Errors

• Rewrite for humans: what happened + how to fix
• High signal-to-noise; group similar errors
• Important info at the end (eye drawn there)
• Unexpected errors → debug path + bug report instructions

Arguments & Flags

• Prefer flags over positional args
• Full-length flags for everything (`--help`, not just `-h`)
• One-letter flags for common options only
• Standard names: `--help`, `--version`, `--dry-run`, `--verbose`, `--json`, `--force`, `--output`, `--quiet`, `--debug`, `--no-input`
• Sensible defaults (right thing for most users)
• Prompt for missing input (TTY only); never require prompts
• Confirm dangerous actions; support `--dry-run`
• `-` for stdin/stdout when flag takes a file
• Order-independent flags/subcommands when possible
• Never accept secrets via flags (use `--password-file` or stdin)

Interactivity

• Prompt only when stdin is TTY
• Support `--no-input` to disable all prompts
• Password prompts: don't echo
• Ctrl-C always exits quickly

Subcommands

• Consistent flags across subcommands
• Consistent naming pattern (noun verb or verb noun)
• Avoid ambiguous names (update vs upgrade)

Robustness

• Validate input early; fail fast with clear message
• Responsive < 100ms; show progress for long ops
• Network calls timeout (configurable)
• Recoverable on rerun; crash-only design
• Handle misuse (scripts, bad networks, concurrent instances)

Future-Proofing

• Treat interfaces as contracts (flags, env vars, config, output)
• Additive changes preferred
• Warn before breaking changes; deprecate gracefully
• No catch-all subcommand (blocks future commands)
• No arbitrary abbreviations of subcommands

Signals

• Ctrl-C: exit immediately, acknowledge, timeout cleanup
• Second Ctrl-C: force stop (document behavior)

Configuration

• Precedence: flags > env > project config > user config > system config
• Follow XDG spec (`~/.config/...`)
• Never silently edit other programs' config

Environment Variables

• Names: `UPPERCASE_WITH_UNDERSCORES` (no leading digit)
• Single-line values preferred
• Respect: `NO_COLOR`, `FORCE_COLOR`, `DEBUG`, `EDITOR`, `HTTP_PROXY`, `PAGER`, `HOME`, `TMPDIR`
• Read `.env` for project context (not as full config)
• Never read secrets from env vars (use files/stdin)

Naming

• Simple, memorable, lowercase
• Dashes only if needed; short but not cryptic
• Easy to type

Distribution

• Single binary when possible
• Easy uninstall (document it)

Analytics

• No telemetry without consent (opt-in preferred)
• Transparent collection; consider alternatives

Quick Reference

For detailed stress-testing checklist, see [references/checklist.md](references/checklist.md).

For complete guidelines with examples, see [references/full-guidelines.md](references/full-guidelines.md).

Language-Specific Notes

Python

• Use `argparse`, `click`, or `typer`
• Return exit codes from `main()`; use `raise SystemExit(main())`
• No tracebacks for expected errors; `--debug` for unexpected
• Handle Ctrl-C cleanly (exit 130, no traceback)
• Separate TTY detection for stdout vs stderr

TypeScript/Node

• Use `commander`, `yargs`, `oclif`, or `node:util parseArgs`
• Separate stdout/stderr; handle async failures
• `--debug` for stack traces
• Avoid premature `process.exit()`; prefer `process.exitCode`

Bash

• Shebang matches features (`#!/usr/bin/env bash` for Bash-only)
• Robust flag parsing; handle quotes/whitespace
• `trap` for cleanup; `mktemp` for temp files
• Lint with `shellcheck`
• use skill: `shellck`