Amazing CLIfor Terminal
Guide

Configuration

Client initialization, authentication, default options

Git2Docs Certified

Overview

This page explains how to install Chalk, configure its color level, and initialize instances for use in your Node.js or browser-bundled application. Chalk is an ESM-only library that wraps terminal output strings in ANSI escape sequences, automatically detecting the host terminal's color capability at runtime. Understanding initialization matters because color level affects every styled string your application produces — getting it wrong silently strips all color or applies escape codes a terminal cannot render. The two primary paths covered here are using the pre-configured default export and creating isolated Chalk instances with explicit color-level settings via the Chalk constructor.


Prerequisites

Before you begin, ensure your environment meets the following requirements:

  • Node.js ≥ 22 — Chalk's package declares >=22 and CI tests against Node 22 and 26 only. Earlier versions are not tested.
  • ESM-compatible project — Chalk is ESM-only. There is no CommonJS build, so your project must use "type": "module" in package.json, or a bundler configured to consume ES modules.
  • npm, pnpm, or yarn — any of these package managers can install Chalk.

Installation
  1. Ensure you are running Node.js ≥ 22. Chalk is tested on Node 22 and Node 26 in CI.

  2. Install Chalk into your project using your preferred package manager:

    npm

    npm install chalk
    

    pnpm

    pnpm add chalk
    

    yarn

    yarn add chalk
    
  3. Because Chalk is ESM-only, your project must import it with import, not require. If your package.json does not already declare "type": "module", either add it or use the .mjs extension for the files that import Chalk.

    {
      "type": "module"
    }
    

    CommonJS note: On Node.js ≥ 22.12, require('chalk') loads the ES module successfully. Access the default export via .default (e.g. const chalk = require('chalk').default). On earlier Node 22 releases, require('chalk') throws ERR_REQUIRE_ESM.

  4. Chalk has no runtime dependencies. ansi-styles and supports-color are vendored internally, so no additional packages are installed into your node_modules.


Configuration

Color level (level)

The central configuration knob in Chalk is the color level, an integer from 0 to 3 that controls which ANSI escape sequences are emitted.

LevelDescription
0All colors disabled — plain strings are returned as-is
1Basic 16-color support
2256-color support
3Truecolor (16 million colors) support

Setting any value outside this range — or a non-integer — throws an error.

Automatic detection (default behavior)

When you use the default chalk export, the level is detected automatically at module load time by inspecting the runtime environment. You do not need to set anything for typical use.

Overriding detection with environment variables

You can force a specific level without changing code:

Variable / FlagEffect
FORCE_COLOR=0Disable all color (level 0)
FORCE_COLOR=1Enable basic color (level 1)
FORCE_COLOR=2Enable 256-color (level 2)
FORCE_COLOR=3Enable Truecolor (level 3)
FORCE_COLOR=true or FORCE_COLOR= (empty)Enable color at level 1 or above; actual level is still detected from the terminal
--no-color flagDisable all color
--color flagEnable basic color
--color=256 flagEnable 256-color mode
--color=16m flagEnable Truecolor mode

Numeric FORCE_COLOR sets the level directly and is capped at 3. The flags --color=256 and --color=16m take precedence over a non-zero numeric FORCE_COLOR.

Setting level on the default instance

You can reassign chalk.level at runtime, but this applies globally to every consumer of the default export in the same process. Prefer creating an isolated instance instead:

import chalk from 'chalk';

// Global override — affects all code using the default export
chalk.level = 1;

Creating an isolated instance with new Chalk({ level })

The Chalk constructor accepts an Options object with one field:

  • level (0 | 1 | 2 | 3 | undefined) — The color level for this instance. Omit it, or pass undefined, to have the level auto-detected from the environment. Throws if the value is not undefined and not an integer from 0 to 3.

This is the recommended approach whenever you need per-stream or per-context control, or are writing a reusable module that should not alter global state:

import { Chalk } from 'chalk';

const noColorChalk  = new Chalk({ level: 0 }); // always plain text
const basicChalk    = new Chalk({ level: 1 }); // 16-color output
const chalk256      = new Chalk({ level: 2 }); // 256-color output
const trueChalk     = new Chalk({ level: 3 }); // Truecolor output
const autoChalk     = new Chalk();             // level auto-detected

chalkStderr

Chalk exports a second pre-configured instance, chalkStderr, whose color level is detected from stderr instead of stdout. Use it when writing diagnostic output to process.stderr:

import { chalkStderr } from 'chalk';

process.stderr.write(chalkStderr.red('Fatal error\n'));

Browser environments

When Chalk is used in a browser bundle, the default condition in the package exports selects a browser-specific color detector that inspects the Chromium brand version instead of terminal flags:

  • Chromium brand version > 93 → level 3 (Truecolor)
  • Any other Chrome/Chromium user agent → level 1
  • No navigator, or a non-Chromium browser → level 0

Since Chrome 69, ANSI escape codes are natively supported in the developer console, so level 3 output renders correctly in modern Chromium-based DevTools.


Usage

Import the default instance

For most scripts and CLI tools, import the default chalk export and start chaining styles immediately. No initialization code is required — the color level is auto-detected.

import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));

Chain styles

Styles are chainable properties. Call the last property in the chain as a function, passing one or more strings. Multiple arguments are joined with a space.

import chalk from 'chalk';

console.log(chalk.blue.bgRed.bold('Hello world!'));
console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar'));

Define reusable style themes

Because a chalk chain without a final call returns a function, you can assign partial chains to variables and reuse them:

import chalk from 'chalk';

const error   = chalk.bold.red;
const warning = chalk.hex('#FFA500');

console.log(error('Error!'));
console.log(warning('Warning!'));

Use an isolated instance for reusable modules

If your module is consumed by other packages, never mutate the global chalk.level. Create an isolated instance instead:

import { Chalk } from 'chalk';

const chalk = new Chalk({ level: 2 }); // 256-color, isolated
console.log(chalk.green('Module output'));

Interpolate values in template literals (standard ES syntax)

Chalk's chainable builder returns a function, so you can use standard ES template literals with ${} interpolation — just call the chalk style as a function inside the expression:

import chalk from 'chalk';

const cpuUsage = '90%';
console.log(`CPU: ${chalk.red(cpuUsage)}`);

Important: Do not use chalk as a tagged template literal (e.g. chalk.red\text`). The core library does not support tagged template literal interpolation. If you need tagged template literal syntax with ${} interpolation, install the separate [chalk-template`](https://github.com/chalk/chalk-template) package.

Write to stderr with chalkStderr

import { chalkStderr } from 'chalk';

process.stderr.write(chalkStderr.yellow('Warning: retrying...\n'));

Disable color output programmatically

import { Chalk } from 'chalk';

const plainChalk = new Chalk({ level: 0 });
console.log(plainChalk.red('This will have no color'));

Examples

Basic colored output

import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));

Chaining multiple styles

import chalk from 'chalk';

console.log(chalk.blue.bgRed.bold('Hello world!'));

Combining styled and plain strings

import chalk from 'chalk';

console.log(chalk.blue('Hello') + ' World' + chalk.red('!'));

Multiple arguments (space-joined)

import chalk from 'chalk';

console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));

Nested styles

import chalk from 'chalk';

console.log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));

Reusable theme definitions

import chalk from 'chalk';

const error   = chalk.bold.red;
const warning = chalk.hex('#FFA500');

console.log(error('Error!'));
console.log(warning('Warning!'));

Using console.log string substitution

import chalk from 'chalk';

const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);
//=> 'Hello Sindre'

Truecolor with RGB and hex

import chalk from 'chalk';

console.log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
console.log(chalk.hex('#DEADED').bold('Bold gray!'));

Isolated instance with explicit color level

import { Chalk } from 'chalk';

const customChalk = new Chalk({ level: 0 });
console.log(customChalk.red('This will not be red'));

Validating style names with exported name arrays

import { modifierNames, foregroundColorNames } from 'chalk';

console.log(modifierNames.includes('bold'));
//=> true

console.log(foregroundColorNames.includes('pink'));
//=> false

Underline color (requires an underline modifier)

import chalk from 'chalk';

console.log(chalk.underlineHex('#DEADED').underlineCurly('Hello, world!'));

Background color methods

import chalk from 'chalk';

console.log(chalk.bgHex('#DEADED').underline('Hello, world!'));
console.log(chalk.bgRgb(15, 100, 204).inverse('Hello!'));

Troubleshooting

ERR_REQUIRE_ESM when calling require('chalk')

Symptom: Your CommonJS file throws Error [ERR_REQUIRE_ESM]: require() of ES Module … not supported.

Cause: You are running Node.js 22 but on a release earlier than 22.12. Those releases cannot require() an ES module.

Fix: Upgrade to Node.js ≥ 22.12, or convert the importing file to ESM (import chalk from 'chalk'). On Node.js ≥ 22.12, require('chalk') works and returns the ES module namespace; access the default export with .default:

const chalk = require('chalk').default;

No color appears in output

Symptom: Terminal output contains no ANSI color — strings appear plain.

Cause (1): The detected color level is 0. This happens when stdout is not a TTY (e.g. the output is piped), when FORCE_COLOR=0 is set, or when --no-color is passed.

Fix: Force a level with an environment variable:

FORCE_COLOR=1 node your-script.js
# or
FORCE_COLOR=3 node your-script.js   # Truecolor

Or use the --color flag:

node your-script.js --color

Cause (2): A Chalk instance was constructed with { level: 0 }.

Fix: Remove the explicit level or set it to the appropriate value:

import { Chalk } from 'chalk';
const chalk = new Chalk({ level: 3 });

Tagged template literal produces garbled or missing interpolations

Symptom: chalk.green\Hello ${name}`printsHello , Sindre` or similar — the interpolated value appears in the wrong position, or the template does not behave like a standard template literal.

Cause: Chalk's chainable builder does not implement tagged template literal semantics. Used as a tag, it receives the raw string array and joins it, so variable interpolation does not work as expected.

Fix: Either call chalk as a regular function with standard ES template literals:

console.log(chalk.green(`Hello ${name}`));

Or install chalk-template for proper tagged template literal support with interpolation.


level setter throws a RangeError-style error

Symptom: Assigning chalk.level = someValue or passing { level: someValue } to new Chalk() throws Error: The \level` should be an integer from 0 to 3`.

Cause: The value is not a safe integer in the range 0–3. Common mistakes include passing true, null, undefined to the constructor's level field (note: passing undefined or omitting level is valid and triggers auto-detection), or a floating-point number.

Fix: Use only integer values 0, 1, 2, or 3. Omit level entirely (or pass undefined) to let Chalk detect the level automatically:

import { Chalk } from 'chalk';

const chalk = new Chalk();             // auto-detect
const chalk2 = new Chalk({ level: 2 }); // explicit 256-color

Colors render differently between stdout and stderr

Symptom: Styled strings sent to process.stderr appear plain or at a lower color level than those sent to process.stdout.

Cause: The default chalk export detects color support for stdout. If stderr is attached to a different TTY or is piped, its detected level may differ.

Fix: Use the chalkStderr export, which is a separate Chalk instance whose color level is independently detected for stderr:

import { chalkStderr } from 'chalk';

process.stderr.write(chalkStderr.red('Error message\n'));