CLI Design

CLI Design: Unix-Composable Command-Line Interfaces

This skill covers language-agnostic CLI design principles. The rules about stream separation, exit codes, format flags, and composability apply regardless of implementation language.

This bundle adapts the CC BY-SA 4.0 Command Line Interface Guidelines. Pinned provenance, modification notes, and license scope are recorded in resources/source-notes.md and LICENSE.

For API contract stability and Hyrum's Law, see the api-design skill. For config, env vars, and graceful shutdown, see the twelve-factor skill.

TypeScript implementation patterns are in the resources/ directory. Load them on demand when building a CLI in TypeScript:

When to Use

• Building any command-line tool (any language)
• Designing command tree, flags, and I/O contracts
• Implementing the output layer (format detection, stream routing)
• Testing CLI behavior (stdout/stderr separation, exit codes)
• Reviewing a CLI for Unix composability

Core Principle

stdout is for DATA only — the product the user asked for. stderr is for EVERYTHING ELSE — diagnostics, progress, spinners, warnings, errors.

This separation is what makes mycli --json | jq ... work. One spinner character on stdout breaks every downstream pipe.

"Whatever software you're building, you can be absolutely certain that people will use it in ways you didn't anticipate. Your software will become a part in a larger system — your only choice is over whether it will be a well-behaved part." — clig.dev

The Unix Stream Contract

Stream behavior:

• Check stdout and stderr independently; stdout being piped does not mean stderr is piped
• Do not assume C stdio's line/block/unbuffered rules describe every language runtime
• In Node.js, sync/async process-stream behavior varies by operating system and destination; always respect .write() backpressure for high-volume output

When stdout is piped, the user doesn't want your status messages in their data. All non-data output must go to stderr.

For a deep dive on buffering behavior and performance implications, see resources/stream-contracts.md.

Keep Handlers Pure

The practical rule: functions that do the work should return data, not write to stdout. The CLI entry point handles all I/O.

Entry point (CLI main)              Your logic (handlers)
─────────────────────               ─────────────────────
parse args                          (input) → structured result
detect format (json/plain/human)    no printing to stdout
call handler                        no writing to stderr
format the result                   no calling exit
write to correct stream             just returns data
set exit code

This isn't an architecture mandate — it's just clean function design with one hard edge: the entry-point file is the only file that writes to a stream or ends the process. When you extend or edit a module that already prints or exits, move that writing into the entry point as part of the same change — do not leave it there, and never add more printing alongside it because "that function already did it". The benefits are concrete:

• Testable without subprocess spawning — call the handler, assert on the returned value
• Format flexibility for free — same data renders as JSON, plain text, or coloured tables by swapping one function
• Reusable — the same handler works from a CLI, MCP server, HTTP API, or programmatic import

For simple CLIs where the "handler" is just calling a library, this separation already exists naturally — your library returns data, your CLI formats it. No extra layers needed.

If your project uses hexagonal architecture, the mapping is direct: the CLI entry point is a driving adapter, and the handler is a use case that returns a result through a port. See the hexagonal-architecture skill — the patterns reinforce each other, but hex arch is not required to benefit from keeping handlers pure.

For TypeScript implementation patterns (Result types, entry point wiring, formatters, logger interfaces), see resources/output-architecture.md.

Selecting a TypeScript Stack

Prefer the command and prompt libraries the repository already owns when they can satisfy the contracts in this skill. For a new material dependency, inspect current versions and project constraints and use evaluate-existing-solutions; do not select from remembered popularity or stale package characteristics.

Stricli can fit typed, injected command handlers, and @clack/prompts can fit optional TTY-gated interactivity. Treat them as candidates, not defaults. Compare them with the existing stack and alternatives on handler testability, type safety, startup cost measured in the target runtime, maintenance, dependency weight, non-interactive behavior, and migration cost.

Format Flag Contract

Three-tier output hierarchy:

Default: Human-Readable

• Colors, tables, formatted text
• Progress bars and spinners on stderr
• Output tailored for terminal width
• May change between versions — this is not a contract

--plain: Grep/Awk-Friendly

• One record per line, no formatting, no colors
• Stable between minor versions — this is a contract
• Flat table rows, no borders, no grouped sections
• Enables: mycli list --plain | grep error | wc -l

"Encourage your users to use --plain or --json in scripts to keep output stable." — clig.dev

--json: Structured Data

• On success, stdout contains ONLY valid JSON — no spinners, no color, no progress
• On any non-zero exit, stdout stays empty and the final non-empty stderr line is the structured JSON error envelope
• That includes a domain failure (exit 1) where the run completed and the numbers exist — an unmet threshold, gate, or budget is a failure, not a success envelope carrying a false flag inside it. If the caller still needs the figures, put them inside error (a details field), never on stdout
• Other diagnostics may precede that final stderr line and never contaminate stdout; consumers parse the final non-empty line rather than the entire diagnostic stream
• Schema is versioned — breaking changes to JSON output are breaking changes to the CLI
• --json implies non-interactive regardless of TTY

Consistent envelopes:

Success on stdout:

{ "ok": true, "data": { ... } }

The envelope is not optional and renames nothing: field names a consumer asked for live unchanged inside data, and a list of records goes in data rather than replacing the envelope with a bare array.

Failure on stderr:

{ "ok": false, "error": { "code": "CONFIG_MISSING", "message": "...", "fix": "..." } }

NDJSON for Streaming

For large datasets, use NDJSON (one JSON text per record, terminated by \n):

• Each line is independently parseable
• Any JSON value is valid NDJSON syntax; the application's decoder owns its schema
• The examples in this skill use an optional local event profile with a type discriminator and an optional final summary record; neither is required by NDJSON
• Document whether readers ignore or reject empty lines
• Enables: mycli run --format ndjson | while read -r line; do ...; done

For NDJSON specification details, see resources/stream-contracts.md.

Exit Codes

Rules:

• Non-zero exit code MUST have a stderr explanation
• Document exit codes in --help
• Never use codes above 125 for application errors (reserved for signals: 128 + signal number)
• Use exit 75 only when no mutation was dispatched or retry safety is established through idempotency/reconciliation; a merely transient cause is not enough
• If a mutating request may have reached its destination, report an ambiguous outcome and direct the user to status/reconcile instead of inviting a blind retry
• A handled SIGTERM may finish with 0 or a documented application status such as 143; Docker and Kubernetes do not require 143 for graceful shutdown
• Map non-zero codes to the most important failure modes for your tool
• A flag the caller simply did not pass is not invalid usage. Exit 2 is for input the tool cannot act on; an added gate, threshold, or filter flag is opt-in — its absence means the check is off and the command still succeeds with 0. Make a new flag required only when the command has no meaning without it, or every plain invocation becomes a usage error and hides the failures the codes exist to separate
• Order the checks so each failure reaches the code that names it: a later validation must not intercept a config or data error and report it as bad usage

TTY Detection

Check priority order (first match wins):

Resolve the output mode once, in the entry point, before anything is written. Walk the table above — format flags, --no-color, FORCE_COLOR, NO_COLOR, TERM, CI, and each stream's TTY status (isatty/isTTY) — into a single mode value and pass it to the formatters. Write that check even when today's output has no color and no animation yet: it is what keeps the decision in one place the day either is added.

Check stdout and stderr independently. When stdout is piped but stderr is a TTY, you can still show spinners on stderr while keeping stdout clean for the pipe consumer. Status lines, spinners and progress are written only when the stream carrying them is a TTY; when stderr is a pipe it carries warnings and errors and nothing else.

Gate prompts on stdin independently. Prompt only when stdin and the prompt's output stream are TTYs; stdout TTY status controls data formatting, not whether input is safe to request.

Optionally support MYCLI_NO_COLOR for app-specific color override.

Input Design

Flags Over Arguments

• 1 positional arg: acceptable (the "main thing")
• 2 positional args: suspicious — consider flags instead
• 3+ positional args: prefer named flags unless a familiar command grammar makes the positions obvious
• Exception: variadic args of the same type are fine (rm a.txt b.txt c.txt), as are universal idioms (cp source dest)

Flags are self-documenting, order-independent, and future-proof.

# Bad — which is source, which is destination?
mycli copy myapp backup

# Good — explicit
mycli copy --from myapp --to backup

Standard Flags

Always provide long forms. Short flags only for the most common operations.

Prompts and Interactivity

• All prompts MUST be bypassable via flags for scriptability
• Confirmation → --yes or --force
• Selection → --type=value
• Text input → --name=value
• Passwords → --password-file=path or stdin pipe
• If stdin is not a TTY, never prompt — fail with a clear error or use defaults
• Secrets: never via flag values (leak to ps output and shell history). Prefer, in order: OS keychain or a 0600 credential file (~/.config/mycli/credentials), then stdin (mycli login --with-token < token.txt), then env vars only where the platform injects them (CI secret stores) — env leaks to child processes and crash reports, so never make it the primary documented path
• Scale confirmation to severity: mild → y/N prompt with --yes bypass; moderate → prompt plus suggest --dry-run first; severe/irreversible (delete a database, overwrite production) → require typing the resource name to confirm

Conventions

• Support -- to stop flag parsing: mycli run -- --flag-for-child-process
• Support - for stdin/stdout file arguments: curl ... | mycli process -
• Accept both --flag=value and --flag value
• If stdin is expected but is an interactive terminal, display help immediately (don't hang like cat)