Design Cli Output

---
name: design-cli-output
locale: wenyan
source_locale: en
source_commit: 2630b6e9
fence_basis_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
---

# 設 CLI 輸出

為命令行具設一致之多層終端輸出。

## 用時

- 為 CLI 工具建新報告模
- 於標交易輸出旁加溫或敘述輸出
- 為多命令統一輸出式
- 與人可讀輸出並設 JSON 機輸出
- 為新終端工具擇色、字符、冗贅級

## 入

- **必要**：CLI 工具名與主受眾（開發者、運者、終用者）
- **必要**：需格式輸出之諸命令
- **可選**：是否欲「儀式」或敘述輸出
- **可選**：品牌約（色板、語調）

## 法

### 第一步：定色板

以 chalk 建名板物。

**載 chalk 於無色退路之後。** 退路須代板所用之諸呼形，非唯傳字符串而已：

```javascript
// 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(); }
```

四恒則，短樁各失其一：

1. **`Proxy` 之標的可呼** — `(text) => text`，非 `{}`。連鎖（`chalk.bold.cyan('x')`）須每節皆可索且可呼。
2. **廠函返函。** `new Proxy({}, { get: () => (s) => s })` 足直式而破廠函：`chalk.hex('#FF6B35')` 遂為*字符串* `'#FF6B35'`，呼之則擲 `TypeError: ... is not a function`。板建於模載之時，故此退路於入模之際即傾其具——正當以純文本降格為旨之境。
3. **`then` 為 `undefined`。** 若樁以函答諸屬，則 `await chalk` 永懸：運行時呼 `.then` 而候無人施之回調。Node 報 `Detected unsettled top-level await` 而退 13。
4. **`level` 為數。** 能力關讀 `chalk.level >= 1`；真值之樁啟之，而其後無色可用。

以歷此入而存者建板。

**標板**（交易輸出）：

```javascript
// 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
```

**溫板**（儀式/敘述輸出）：

```javascript
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)
};
```

板設之則：
- 恒供無色退路，且以板實用之諸呼形驗之——上之溫板幾盡廠函
- 自定板用十六進色（`chalk.hex('#FF6B35')`）
- fail/error 色無論板主題恒為紅
- 以語義角命板項，非以視外觀
- 諸模共一樁，勿於各入處重建，否則同疵須逐本尋而修

**得：** 板物附名項，且其退路已執，非徒書之。

**敗則：** 直試退路之途；板非發其壞之所。樁在域中則：

```javascript
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` 不覆此。彼試*可用*之 chalk 而擇不出逸碼；退路試入模已敗之 chalk。二途無共碼。全註之產樁、疵之重現、及上諸察之可執本，見
[Extended Examples](references/EXAMPLES.md#step-1-the-no-color-chalk-fallback)。

### 第二步：擇狀指

擇 Unicode 字符或 ASCII 字為狀通：

**ASCII（最大兼容）：**

```text
+  created/installed (green)
-  removed/deleted (red)
=  skipped/unchanged (dim)
!  error/warning (red)
```

**Unicode（豐，需 UTF-8 終端）：**

```text
✦  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)
```

擇之則：
- CI 或管境之工具用 ASCII
- 交互終端用者用 Unicode
- 以 `--ascii` 旗或 `NO_COLOR` 察二者皆供
- 於諸境測字符：macOS Terminal、Windows Terminal、VS Code terminal、SSH 會

**得：** 字符集，一目可通狀而不唯賴色。

**敗則：** 若測中字符渲為 `?` 或方塊，替以 ASCII 等。`+/-/=/!` 集處處可。

### 第三步：設冗贅級

各命令宜支四輸出級：

| 級 | 旗 | 受眾 | 內容 |
|---|---|---|---|
| **默** | （無） | 終端之人 | 格式、著色、資訊 |
| **詳** | `--verbose` 或 `--ceremonial` | 欲詳之人 | 逐項細、至序 |
| **靜** | `--quiet` | 腳本、CI | 最少行、狀圖、無飾 |
| **JSON** | `--json` | 機消費者 | 結構、可解、全 |

實模：

```javascript
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 輸出之則：
- 恒有效 JSON（勿混人文本）
- 含人輸出諸數，加機有用字段
- 跨命令用一致鑰名
- 成退 0，錯退 1（不論輸出模）

**得：** 四清輸出級，跨命令行為一致。

**敗則：** 若詳模過噪，設為自選（`--ceremonial`）而非漸進級。

### 第四步：立語則

定諸輸出函從之語調式。防跨命令不一致。

語則例（由營火報告）：

1. **現時、主動**：「mystic arrives」非「mystic has been installed」
2. **無歎**：靜信。工具不喊。
3. **隱喻替術語**：「practices」非「dependencies」（唯儀式模）
4. **敗誠實非災**：「A spark was lost」非「ERROR: installation failed with exit code 1」
5. **末行反狀**：各操以狀總結
6. **無 emoji**：Unicode 字符承視重而非裝
7. **每字承資**：若字不加解，除之

標（非儀式）輸出之語則：
- 簡實之行
- 狀圖+項 ID+脈
- 含計之總行
- 錯示糾動

**得：** 書 3-7 語則，諸輸出函宜從。

**敗則：** 若則似妄，驗之：書同輸出有無各則。若除則不變質，則非需。

### 第五步：實報告函

組輸出入報告模，附聚能：

```javascript
// 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 };
```

各函從同結構：
1. 優理空/空輸
2. 算布局（列寬、墊）
3. 以板色輸
4. 底總行

儀式輸出建獨模：

```javascript
// 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) { ... }
```

**得：** 報告函獨可用——各理自格式無賴呼狀。

**敗則：** 若函長於約 50 行，抽助者。報告函宜易獨察。

### 第六步：跨境測輸出

驗輸出於異脈正渲：

```bash
# 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'
```

察：
- 交互模色正顯
- ANSI 逸碼不漏入管/重定輸
- JSON 有效（管至 `jq .` 驗）
- Unicode 字符於目標終端渲
- 列齊於變寬內容守
- 無色退路答板所用之諸呼形，且斷言於試集，非徒手示一回

**得：** 六境輸出皆正。

**敗則：** 若 ANSI 漏，確 chalk 守 `NO_COLOR`。若 Unicode 壞，供 ASCII 退模。又須知綠試集於色無所證：試行者管 stdout，`chalk.level` 遂為 0，著色與未著色之輸出逐字節同，故色全壞而諸斷言猶立。證色可用須 `FORCE_COLOR=3` 及對逸碼之斷言。

## 驗

- [ ] 色板有無色退路，且退路已執：直式、廠函、連鎖、`level === 0`、`await` 皆察
- [ ] 狀指於色與無色模皆可
- [ ] 四冗贅級皆生有用輸出
- [ ] JSON 輸出有效且 `jq` 可解
- [ ] 語則已記且一致從
- [ ] 報告函優理空/空輸
- [ ] 輸出於下諸境皆測：terminal、管、NO_COLOR、CI

## 陷

- **唯理直式之無色退路**：`new Proxy({}, { get: () => (s) => s })` 讀似完備，且誠覆 `chalk.dim` 與 `chalk.red`，然諸廠函遂返字符串，而呼者即刻呼之。板建於模載，故 `TypeError` 落於入模之時——退路正於其所以存之一境敗之最劇。第一步列樁須足之四恒則。
- **混人文本與 JSON**：`--json` 模唯出有效 JSON。一孤行（如「DRY RUN」）破 JSON 解。若命令宜示二者，明分或於 JSON 模抑人文本。
- **硬編列寬**：內容長變。以 `Math.max(...items.map(i => i.id.length))` 動算墊。
- **色無義**：若色為別成敗唯徑，色盲用者與管輸失資。恒色配文指（`+`、`OK`、`ERR`）。
- **儀式於誤境**：溫敘輸出宜交互終端會。於 CI、腳、`--quiet` 模，添噪。儀式輸出置明旗後。
- **忘總行**：用者先掃末行。諸操宜以單行總結（成/敗/跳計）。

## Related Skills

- `scaffold-cli-command` — 用此輸出之命令
- `test-cli-application` — 測輸出合期
- `build-cli-plugin` — 插件經此輸出系報結