design-cli-output

name	design-cli-output
locale	wenyan-lite
source_locale	en
source_commit	2630b6e9
translator	Julius Brussee homage — caveman
translation_date	2026-07-30
description	Design 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 module, adding warm narrative output to an existing tool, standardizing output across multiple commands, or designing machine-readable JSON alongside human-readable text.
license	MIT
allowed-tools	Read Write Edit Bash Grep Glob
metadata	{"author":"Philipp Thoss","version":"1.0","domain":"cli","complexity":"basic","language":"TypeScript","tags":["cli","terminal","ux","chalk","unicode"]}

Design CLI Output

為命令列工具設計一致之多層終端輸出。

適用時機

• 為 CLI 工具建新 reporter 模組
• 於標準事務性輸出之外加暖或敘事輸出
• 於多指令間統一輸出格式
• 設計與人類可讀輸出並行之 JSON 機器輸出
• 為新終端工具擇色、圖符與冗長度

輸入

• 必需：CLI 工具名與主要受眾（開發者、運維、終端用戶）
• 必需：需輸出格式化之指令
• 可選：是否需「儀式」或敘事輸出變體
• 可選：品牌約束（色盤、語氣）

步驟

步驟一：定色盤

用 chalk 建命名色盤物件。

載 chalk 於無色回退之後。 回退須代色盤所用之每一呼叫形，非僅傳字串而已：

// 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
       ( prop === )  .(target, prop);
       .(prop) ?  () : ();
    },
  });
}

 chalk;
 { chalk = ( ()).; }
 { chalk = (); }