cli-design
Installation
SKILL.md
CLI Design: Unix-Composable Command-Line Interfaces
This skill covers language-agnostic CLI design principles. Apply them proportionately to the tool's users, compatibility promises, platforms, and existing conventions.
Read repository instructions and inspect the existing command surface before changing it. Existing flags, output schemas, exit codes, shell completions, and automation consumers are public contracts even when they were not designed deliberately.
TypeScript implementation patterns are in the resources/ directory. Load them on demand when building a CLI in TypeScript:
| Resource | Load when... |
|---|---|
output-architecture.md |
Implementing Result types, entry point wiring, formatters, logger, JSON envelope schemas |
testing-cli.md |
Writing Vitest tests for CLI behavior (streams, exit codes, pipes, contract tests) |
stream-contracts.md |
Understanding Node.js buffering, NDJSON, signal handling, crash-only design |
composability.md |
Designing or testing pipe behavior — worked shell examples (jq filtering, NDJSON streaming, stdin, chaining, --fields, parallel xargs) |
The TypeScript resources are implementation examples, not requirements. Preserve the project's language, framework, and test conventions.