design-cli-outputDesign terminal output for a CLI tool with chalk colors, Unicode glyphs, multiple verbosity levels (human, verbose, quiet, JSON), and consistent voice rules. Covers color palette selection, status indicator design, reporter function architecture, ceremony/narrative output variants, and cross-terminal compatibility. Use when building a new CLI reporter modul…
Independent GitHub snapshot · Automated classification · Original documentation governs
Consistent multi-level terminal output for CLI.
chalk → named palette.
Load chalk behind no-color fallback. Fallback must stand in for every call shape palette uses — more than passing strings thru:
// 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(); }
4 invariants, shorter stub gets each wrong:
(text) => text, not {}. Chain (chalk.bold.cyan('x')) → every hop indexable + callable.new Proxy({}, { get: () => (s) => s }) OK for direct styles, breaks factories: chalk.hex('#FF6B35') = string '#FF6B35', call it → TypeError: ... is not a function. Palettes built at module load → that fallback kills tool at import time — exactly where degrading to plain text was the point.then = undefined. Stub answering every prop w/ fn → await chalk hangs forever: runtime calls .then, waits for callback nobody fires. Node: Detected unsettled top-level await, exit 13.level = number. Capability gates read chalk.level >= 1; truthy stub opens them w/ no color behind.Build palette from whichever obj survived that import.
Standard (transactional):
// Status colors
const ok = chalk.green; // success
const fail = chalk.red; // errors
const warn = chalk.yellow; // warnings
const info = chalk.cyan; // identifiers, names
const dim = chalk.dim; // secondary info, paths
const bold = chalk.bold; // headers
Warm (ceremony/narrative):
const C = {
flame: chalk.hex('#FF6B35'), // active elements, fire
amber: chalk.hex('#FFB347'), // arriving items, warm highlights
spark: chalk.hex('#FFF4E0'), // individual items (sparks/skills)
ember: chalk.hex('#8B4513'), // cold/dormant states
warm: chalk.hex('#D4A574'), // neutral warm text
dim: chalk.dim, // background, secondary
fail: chalk.red, // errors stay red (honest)
};
Rules:
chalk.hex('#FF6B35'))→ Palette obj w/ named entries + fallback that ran, not merely written.
If err: Exercise fallback path direct; palette = wrong place to find it broken. Stub in scope:
console.assert(chalk.dim('x') === 'x'); // direct style
console.assert(chalk.hex('#fff')('x') === 'x'); // factory — the usual defect
console.assert(chalk.bold.cyan('x') === 'x'); // chain
console.assert(chalk.level === 0); // capability gate stays shut
await chalk; // must not hang
NO_COLOR=1 no cover this. It runs working chalk choosing no escapes; fallback runs chalk that failed import. 2 paths share no code. See More Ex → annotated prod stub, defect repro, runnable ver of checks above.
Unicode glyphs or ASCII:
ASCII (max compat):
+ created/installed (green)
- removed/deleted (red)
= skipped/unchanged (dim)
! error/warning (red)
Unicode (richer, UTF-8 term):
✦ item/skill/practice (spark)
◉ active/burning state
◎ cooling/embers state
○ cold/dormant state
◌ available/not installed
✗ failed item
✓ success (use sparingly — not all terminals render it well)
Criteria:
--ascii flag or NO_COLOR→ Glyph set communicates status at glance w/o color alone.
If err: Glyph renders ? or box → ASCII equiv. +/-/=/! works everywhere.
Every cmd supports 4:
| Level | Flag | Audience | Content |
|---|---|---|---|
| Default | (none) | Human at terminal | Formatted, colored, informative |
| Verbose | --verbose or --ceremonial | Human wanting detail | Per-item breakdown, arrival sequences |
| Quiet | --quiet | Scripts, CI | Minimal lines, status icons, no decoration |
| JSON | --json | Machine consumers | Structured, parseable, complete |
Pattern:
function output(data, options) {
if (options.json) {
console.log(JSON.stringify(data, null, 2));
return;
}
if (options.quiet) {
for (const item of data.items) {
const icon = item.ok ? '+' : '!';
console.log(`${icon} ${item.id}`);
}
return;
}
// Default (or verbose) human output
printFormatted(data, { verbose: options.verbose });
}
JSON rules:
→ 4 clear levels, consistent behavior across cmds.
If err: Verbose too noisy → opt-in (--ceremonial) not graduated.
Tone + style. Prevents inconsistency.
Ex (campfire reporter):
Standard (non-ceremony):
→ 3-7 voice rules output fns follow.
If err: Rules arbitrary → test. Write same output w/ + w/o rule. If no change → rule not needed.
Module w/ focused fns:
// reporter.js — standard output
export function printResults(results) { ... }
export function printItemTable(items) { ... }
export function printDetections(detections) { ... }
export function printAudit(auditResults) { ... }
export function printDryRun() { ... }
export function warn(msg) { ... }
export function error(msg) { ... }
export { chalk };
Each fn:
Ceremony → separate module:
// campfire-reporter.js — warm narrative output
export function printArrival({ teamId, agents, results, ceremonial }) { ... }
export function printScatter({ teamId, agents, results }) { ... }
export function printTend(fires) { ... }
export function printCampfireList({ teams, state, reg }) { ... }
export function printFireSummary({ team, fireData, reg }) { ... }
export function printJson(data) { ... }
→ Independent fns, handle own formatting w/o caller state.
If err: Fn >~50 lines → extract helpers. Reviewable in isolation.
# With colors (interactive terminal)
node cli/index.js list --domains
# Without colors (piped)
node cli/index.js list --domains | cat
# With NO_COLOR environment variable
NO_COLOR=1 node cli/index.js list --domains
# JSON mode (parseable)
node cli/index.js campfire --json | jq .
# In CI (typically no TTY)
CI=true node cli/index.js audit
# The no-color fallback. A failed import cannot be provoked with an env var, so
# assert on the stub itself in the suite rather than reaching it through the CLI.
# Pass a glob, not a directory: `node --test <dir>` stopped expanding at Node 22.
node --test 'cli/test/*.test.js'
Check:
jq .)→ Output correct in all 6 contexts.
If err: ANSI leaks → chalk respects NO_COLOR. Unicode breaks → ASCII fallback. Green suite says nothing about color either way: test runners pipe stdout → chalk.level 0 → colored + uncolored out byte-identical, assertions hold w/ color fully broken. Prove color works → FORCE_COLOR=3 + assert on escape seq.
level === 0, await all checkedjq-parseablenew Proxy({}, { get: () => (s) => s }) reads complete, does cover chalk.dim + chalk.red, but every factory then returns string caller immediately tries to call. Palettes built at module load → TypeError lands at import time — fallback fails hardest in the 1 case it exists for. Step 1 lists 4 invariants stub must satisfy.--json only valid JSON. Stray line ("DRY RUN") breaks parsers. Suppress human in JSON mode.Math.max(...items.map(i => i.id.length)) dyn.+, OK, ERR).--quiet = noise. Gate behind flags.scaffold-cli-command — cmds using this outputtest-cli-application — test output matchesbuild-cli-plugin — plugins report results