CLI Design: Unix-Composable Command-Line Interfaces

api-design

twelve-factor

resources/

output-architecture.md

testing-cli.md

stream-contracts.md

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

mycli --json | jq ...

"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

• stdout: line-buffered when connected to a TTY, block-buffered when piped (~2x faster than stderr)
• stderr: unbuffered — every write is a syscall (immediate but expensive)
• Check each stream independently — stdout being piped does not mean stderr is piped

resources/stream-contracts.md

Keep Handlers Pure

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

• 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

hexagonal-architecture

resources/output-architecture.md

Format Flag Contract

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

• stdout contains ONLY valid JSON — no spinners, no color, no progress
• stderr continues normally — human diagnostics still visible
• Errors are structured JSON too — not just success responses
• Schema is versioned — breaking changes to JSON output are breaking changes to the CLI

• --json

  implies non-interactive regardless of TTY

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

NDJSON for Streaming

\n

• Each line is independently parseable
• Include a

  type

  field per record for multiplexing events
• Final line can be a summary record
• Enables:

  mycli run --format ndjson | while read -r line; do ...; done

resources/stream-contracts.md

Exit Codes

• 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)
• Exit code 75 (transient) is critical — it tells retry logic the failure may be temporary
• Map non-zero codes to the most important failure modes for your tool

TTY Detection

--format json

--json

--no-color

NO_COLOR

FORCE_COLOR

TERM=dumb

CI=true

!isatty(stdout)

MYCLI_NO_COLOR

Input Design

Flags Over Arguments

• 1 positional arg: acceptable (the "main thing")
• 2 positional args: suspicious — consider flags instead
• 3+ positional args: never acceptable

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

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

Standard Flags

-h

--help

--version

-q

--quiet

-v

--verbose

-d

--debug

-f

--force

-n

--dry-run

--json

--plain

--no-color

--no-input

-o

--output

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 via files/stdin/env only — never via flag values (they leak to

  ps

  output and shell history)

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

  )

Config Precedence

1. Flags — per-invocation overrides
2. Environment variables —

   MYCLI_*

   prefix, per-session
3. Project config —

   .myclirc

   ,

   mycli.config.ts

   , or in

   package.json

4. User config —

   ~/.config/mycli/

   (follow XDG spec)
5. Defaults — sensible built-in values

• Follow the XDG Base Directory Specification for config file locations
• Env var naming:

  MYCLI_*

  prefix, uppercase letters + digits + underscores
• Never accept secrets via flags — use env vars, files, or stdin
• Read

  .env

  where appropriate, but don't use it as a substitute for proper config
• If you modify configuration that belongs to another program, ask consent first

Error Design

1. Machine-readable code —

   UPPER_SNAKE_CASE

   (e.g.

   CONFIG_MISSING

   ,

   AUTH_EXPIRED

   )
2. What went wrong — context: which resource, operation, input
3. How to fix it — exact command or action the user should take
4. Reference — docs URL or

   mycli help <topic>

   (optional)

Human Mode

Error: CONFIG_MISSING — Configuration file not found
No configuration file found at ./mycli.config.ts or ~/.config/mycli/config.ts

Fix: Run `mycli init` to create a default configuration file
Docs: https://mycli.dev/docs/configuration

• Put the most important information last (the eye is drawn to the end)
• Use red sparingly and intentionally
• Suggest corrections for typos ("Did you mean 'deploy'?")
• Group similar errors under one header — don't repeat 50 similar-looking lines
• Write debug logs to a file, not the terminal (unless

  --debug

  )

JSON Mode

{
  "ok": false,
  "error": {
    "code": "CONFIG_MISSING",
    "message": "No configuration file found at ./mycli.config.ts",
    "fix": "Run `mycli init` to create a default configuration file",
    "transient": false
  }
}

transient

Composability Patterns

# Filter structured output
mycli list --json | jq '.data[] | select(.status == "failed")'

# Stream results for large datasets
mycli run --format ndjson | while read -r line; do echo "$line" | jq '.file'; done

# Feed stdin
cat previous-results.json | mycli report --format markdown

# Combine with other tools
mycli run --json | mycli diff --baseline previous.json

# Silent mode for CI — only exit code matters
mycli check --quiet || echo "Check failed!"

# Chain: create outputs an identifier, next command uses it
mycli create --json | jq -r '.data.id' | xargs mycli deploy --id

# Column selection for efficiency
mycli list --json --fields name,status,id | jq '.data[]'

# Parallel processing
mycli list --json --fields id | jq -r '.data[].id' | xargs -P4 mycli process --id

• Create commands output identifiers so subsequent commands can chain
• List commands support

  --fields

  for column selection (reduces output size, critical for agent efficiency)

• --quiet

  for CI scripts that only care about the exit code
• NDJSON for streaming large datasets without buffering everything in memory

• --dry-run

  with

  --json

  outputs planned changes as structured data

Subcommand Design

• noun verb pattern is most common:

  mycli config set

  ,

  mycli report generate

• Be consistent across all subcommands — same flag names for same things
• No ambiguous pairs (

  update

  vs

  upgrade

  is confusing)
• No catch-all subcommands (you can never add subcommands with conflicting names)
• No arbitrary abbreviations — aliases must be explicit and stable
• With no args: list subcommands (multi-command CLI) or show help (single-command CLI)

Help

• mycli --help

  — top-level help

• mycli help <subcommand>

  — subcommand help

• mycli <subcommand> --help

  — same as above
• If run with missing required args, show concise help + 1-2 examples + "use --help for more"
• Examples are the most-read section — lead with them
• Include flag types, defaults, and allowed values for finite sets

Output Stability Contract

Anti-Patterns

mycli list | jq .

isatty(stdout)

NO_COLOR

--yes

--force

-q

console.log

--fields

--quiet

--json

Verification Checklist

• stdout has ONLY data; stderr has everything else
• Every command supports

  --json

  with consistent envelope
• Exit codes are semantic and documented in

  --help

• Every prompt has a

  --yes

  /

  --force

  /

  --flag

  bypass
• Errors include: code, message, fix suggestion

• --dry-run

  available for mutating commands
• Progress/spinners go to stderr, never stdout

• NO_COLOR

  ,

  TERM=dumb

  , and

  --no-color

  respected
• Piped output contains zero ANSI escape codes
• Success output includes next-action guidance
• Existing flags, exit codes, output fields never removed or renamed
• JSON schema is versioned (additions safe, removals breaking)
• Config follows flags > env > project > user > defaults
• Secrets accepted only via files/stdin/env, never via flags
• Startup < 500ms, print something in < 100ms
• Ctrl-C exits fast with bounded cleanup

• --help

  includes 2-3 realistic examples
• Human output is grep-parseable (flat rows, no table borders)

Quick Reference

Stream Routing

stdout ← data, results, JSON, NDJSON
stderr ← progress, spinners, warnings, errors, debug, prompts

Format Hierarchy

Default (TTY)     → colors, tables, formatted text
--plain           → one record per line, stable, grep-friendly
--json            → structured JSON, versioned schema
--format ndjson   → streaming, one JSON object per line

Exit Codes

0   success
1   domain failure
2   invalid usage
75  temporary failure (retry)
78  config error
130 SIGINT (Ctrl-C)
143 SIGTERM

Config Precedence

flags > env vars > project config > user config > defaults

Flags Cheat Sheet

-h  --help        Show help
    --version     Print version
-q  --quiet       Less output
-v  --verbose     More output
-d  --debug       Diagnostic output
-f  --force       Skip prompts
-n  --dry-run     Preview changes
    --json        Structured JSON
    --plain       Grep-friendly text
    --no-color    Disable color
    --no-input    No prompts
-o  --output      Output file
    --fields      Select columns