Colour levels

colorLevel(rt, { json }) is chalk's level — 0 none, 1 sixteen colours, 2 256, 3 truecolor — decided by the rule below, which is chalk's own apart from the places this page names.

The rule, in orderCopy Anchor Link

1. --json — always 0. Structured output carries no escapes, even when forced.
2. NO_COLOR — set and not empty: 0, whatever else is set.
3. FORCE_COLOR=0 or FORCE_COLOR=false — 0. An explicit "off" is settled before any flag is read, so --color=256 cannot turn it back on.
4. The --color flags, when the runtime carries argv; a flag beats any FORCE_COLOR but 0: --no-color, --no-colors, --color=false and --color=never are 0; --color=16m, --color=full and --color=truecolor are 3; --color=256 is 2; --color and --colors turn colour on and let the terminal decide how much. Flags after -- are the program's, not these.
5. FORCE_COLOR — a number is an exact level, clamped to 3 (FORCE_COLOR=2 is 2, not "2 or better"); true or empty turns colour on and lets the terminal decide.
6. No instruction at all: a pipe is 0, and so is CLI_ACCESSIBLE, because escape codes are noise to a screen reader. Azure Pipelines (TF_BUILD and AGENT_NAME) is the one pipe chalk colours, and so does this.
7. Once colour is on, by a terminal or by an instruction: TERM=dumb is the floor; a CI run gets its vendor's level — GitHub Actions, Gitea Actions and CircleCI truecolor, Travis, AppVeyor, GitLab, Buildkite, Drone and Codeship 16 colours; otherwise COLORTERM=truecolor is 3, a TERM ending in -256color is 2, and a colour-capable TERM is 1.

import { colorLevel, outputMode } from 'roundel/policy';

const cases = [
  ['a terminal, TERM=xterm-256color', { env: { TERM: 'xterm-256color' }, isTTY: { stdout: true } }],
  ['a pipe, TERM=xterm-256color', { env: { TERM: 'xterm-256color' }, isTTY: { stdout: false } }],
  ['a pipe, FORCE_COLOR=true, COLORTERM=truecolor', { env: { FORCE_COLOR: 'true', COLORTERM: 'truecolor' }, isTTY: { stdout: false } }],
  ['a terminal, NO_COLOR=1, --color=16m', { env: { NO_COLOR: '1' }, argv: ['--color=16m'], isTTY: { stdout: true } }],
  ['a terminal, FORCE_COLOR=0, --color=256', { env: { FORCE_COLOR: '0' }, argv: ['--color=256'], isTTY: { stdout: true } }],
  ['a terminal, --no-color', { env: { COLORTERM: 'truecolor' }, argv: ['--no-color'], isTTY: { stdout: true } }],
  ['GitHub Actions log, FORCE_COLOR=true', { env: { CI: 'true', GITHUB_ACTIONS: 'true', FORCE_COLOR: 'true' }, isTTY: { stdout: false } }],
  ['a terminal, CLI_ACCESSIBLE=1', { env: { CLI_ACCESSIBLE: '1', COLORTERM: 'truecolor' }, isTTY: { stdout: true } }],
];

for (const [name, rt] of cases) console.log(`${outputMode(rt).padEnd(10)} ${colorLevel(rt)}  ${name}`);
const forced = { env: { FORCE_COLOR: '3' }, isTTY: { stdout: true } };
console.log(`${outputMode(forced, { json: true }).padEnd(10)} ${colorLevel(forced, { json: true })}  --json, even with FORCE_COLOR=3`);

tty        2  a terminal, TERM=xterm-256color
pipe       0  a pipe, TERM=xterm-256color
pipe       3  a pipe, FORCE_COLOR=true, COLORTERM=truecolor
tty        0  a terminal, NO_COLOR=1, --color=16m
tty        0  a terminal, FORCE_COLOR=0, --color=256
tty        0  a terminal, --no-color
ci         3  GitHub Actions log, FORCE_COLOR=true
accessible 0  a terminal, CLI_ACCESSIBLE=1
json       0  --json, even with FORCE_COLOR=3

Where it differs from chalkCopy Anchor Link

• NO_COLOR. chalk 6.0.0's colour detection does not read it; here it outranks everything.
• A flag beats an ambient FORCE_COLOR. In chalk a set FORCE_COLOR overwrites the flag's answer, so --no-color on a machine that exports FORCE_COLOR=3 still colours. Here the flag typed for this run wins — except that FORCE_COLOR=0 is an "off", and off always wins.
• CLI_ACCESSIBLE and --json. chalk has neither; here each is level 0 without an explicit ask, and --json even with one.
• No emulator allow-list. chalk also recognises particular terminal programs — TERM_PROGRAM, kitty, ghostty, wezterm, TeamCity and the Windows build number. This does not: a program on one of those terminals that reports nothing through TERM or COLORTERM asks for colour with FORCE_COLOR or --color.
• The level is per façade. Setting chalk.level on roundel/chalk changes roundel/chalk and nothing else; the tokens keep reading the policy.

Apart from the allow-list, a differential sweep of 3,000 random environments per partition against chalk 6.0.0's own colour detection found no divergence except where a --color flag and FORCE_COLOR are both set, which is the second point above; policy.test.ts records it.