• 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

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

• 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

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

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

• 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

• 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": "..." } }

\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

• 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

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

undefined

• 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)

• 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

  )

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

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)

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

  )

• 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)

• 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

• 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)