notque/vexjoy-agent / skills/engineering/cli-design
cli-design
VerifiedDesign a CLI interface: args, flags, help, output, errors, exit codes, config.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.7 KB |
| references/clig-checklist.md | markdown | 4.6 KB |
references/clig-checklist.md
View on GitHub# CLI Design Checklist
Condensed from the Command Line Interface Guidelines (https://clig.dev/, CC BY-SA). Rebuilt for this toolkit: Linux-only, spec-focused. Apply each section while filling the spec skeleton in SKILL.md.
## Philosophy
- Human-first: optimize default output for humans; keep scripts working via stable modes (`--json`, `--plain`, exit codes).
- Composability: assume your output becomes someone else's input. Respect stdio, exit codes, signals.
- Consistency: reuse standard flag names and conventions; break a convention only deliberately and document why.
- Say just enough: make progress visible, keep success output brief.
- Conversation: design for trial-and-error loops — previews, dry runs, recoverable errors, suggested next commands.
## Basics
- Use a real argument-parsing library (built-in or reputable), because hand-rolled parsers drift from conventions.
- Exit `0` on success, non-zero on failure; map the few failure modes callers branch on.
- Primary output to stdout; messages, logs, and errors to stderr.
## Help
- Support `-h` and `--help`; help ignores other args.
- On missing required args: concise usage + 1–2 examples + pointer to `--help`.
- Subcommand CLIs: support `mycmd help sub` and `mycmd sub --help`.
- Lead help with examples; list common flags first.
## Output
- Detect TTY: human formatting when interactive, plain when piped.
- Offer `--plain` (stable line-based) and/or `--json` for parsing.
- On state change, say what changed and the new state.
- `-q/--quiet` trims success output when scripts want silence.
- Color: use sparingly; disable when stdout is not a TTY, `NO_COLOR` is set, `TERM=dumb`, or `--no-color` given.
- Animations and progress bars only when stdout is a TTY.
## Errors
- Catch expected errors and rewrite for humans; reserve stack traces for `--debug`, because traces scare users and bury the fix.
- Keep signal-to-noise high; group repeated errors; put the most important line last.
- On unexpected crash: point to debug log location and bug-report path.
## Arguments and flags
- Prefer flags over positional args; positionals only for one obvious repeated item (`rm a b c`).
- Every flag has a long form; reserve one-letter forms for the most common.
- Standard names:
| Flag | Meaning |
|---|---|
| `-h, --help` | help |
| `--version` | version to stdout |
| `-q, --quiet` | less output |
| `-v, --verbose` | more output (`-v` means verbose, version stays long-form) |
| `-d, --debug` | debug output |
| `-f, --force` | skip confirmation |
| `-n, --dry-run` | preview only |
| `--json` | structured output |
| `-o, --output <file>` | output path |
| `--no-input` | disable prompts |
- Support `-` for stdin/stdout where input/output is a file.
- Secrets travel via `--secret-file` or stdin, because flag values leak through `ps` and shell history.
- Defaults serve most users without aliases.
## Interactivity
- Prompt only when stdin is a TTY.
- `--no-input`: prompts off; missing required input fails with an actionable message.
- Password prompts disable echo.
- Destructive ops: interactive confirmation; non-interactive requires `--force`.
## Subcommands
- Use subcommands when complexity demands; share global flags, config, and help.
- Pick noun-verb or verb-noun and stay consistent.
- Keep pairs sharply distinct (`update` vs `upgrade`); reject ambiguous abbreviations, because accepted abbreviations become contracts.
## Robustness
- Validate early; fail fast with a clear message.
- Print something within 100ms, especially before network I/O.
- Timeouts on network calls, configurable.
- Make reruns safe: idempotent where possible, crash-only recovery where feasible.
- Ctrl-C exits fast with bounded cleanup; a second Ctrl-C may force, and says so.
## Configuration and environment
- Per-invocation: flags. Per-user: env or XDG config file. Per-project: checked-in config file.
- Precedence (high → low): flags > env > project config > user config > system config.
- Env var names: uppercase, digits, underscores. Respect `NO_COLOR`, `DEBUG`, `EDITOR`, `PAGER`, `TERM`, `TMPDIR`, `HOME`.
- Modify other programs' config only with consent; prefer adding new files over editing existing ones.
## Future-proofing
- Args, flags, subcommands, config, env vars, and output modes are contracts. Keep changes additive; deprecate loudly and early with a migration path.
- Let human output evolve; keep `--plain`/`--json` stable for scripts.
## Naming and distribution
- Name: short, lowercase, memorable, easy to type, low collision risk.
- Prefer a single binary or a self-contained script; make uninstall easy.
- Telemetry only with explicit opt-in consent, stating what, why, and retention.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |