design-cli-output

Design CLI Output

Design consistent, multi-level terminal output for a command-line tool.

When to Use

• Building a new reporter module for a CLI tool
• Adding warm or narrative output alongside standard transactional output
• Standardizing output format across multiple commands
• Designing JSON machine output parallel to human-readable output
• Choosing colors, glyphs, and verbosity levels for a new terminal tool

Inputs

• Required: CLI tool name and primary audience (developers, operators, end users)
• Required: Commands that need output formatting
• Optional: Whether a "ceremony" or narrative output variant is desired
• Optional: Branding constraints (color palette, tone)

Procedure

Step 1: Define the Color Palette

Use chalk to create a named palette object.

Load chalk behind a no-color fallback. The fallback has to stand in for every call shape the palette uses, which is more than passing strings through:

// A factory returns a *function*; a direct style returns a string. Enumerate
// this list against the installed chalk, not from memory — chalk 6 added the
// three underline* variants, and a list that omits them is wrong for those names.
const FACTORIES = new Set(['ansi256', 'bgAnsi256', 'bgHex', 'bgRgb', 'hex',
  'rgb', 'underlineAnsi256', 'underlineHex', 'underlineRgb']);

function makeChalkStub() {
  return new Proxy((text) => text, {
    get(target, prop) {
      if (prop === 'then') return undefined;   // must not be a thenable
      if (prop === 'level') return 0;          // no color support, truthfully
      if (typeof prop === 'symbol') return Reflect.get(target, prop);
      return FACTORIES.has(prop) ? () => makeChalkStub() : makeChalkStub();
    },
  });
}

let chalk;
try { chalk = (await import('chalk')).default; }
catch { chalk = makeChalkStub(); }

Four invariants, each of which a shorter stub gets wrong:

1. The proxy target is callable — (text) => text, not {}. Chaining (chalk.bold.cyan('x')) needs every hop to be both indexable and callable.
2. Factories return a function. new Proxy({}, { get: () => (s) => s }) satisfies the direct styles and breaks the factories: chalk.hex('#FF6B35') is then the string '#FF6B35', and calling it throws TypeError: ... is not a function. Palettes are built at module load, so that fallback takes the tool down at import time — in precisely the situation where degrading to plain text was the point.
3. then is undefined. A stub that answers every property with a function makes await chalk hang forever: the runtime calls .then and waits for a callback nobody invokes. Node reports Detected unsettled top-level await and exits 13.
4. level is a number. Capability gates read chalk.level >= 1; a truthy stub opens them with no color support behind them.