Amazing CLIfor Terminal
Tutorial

Getting Started

Installation and first API call

Git2Docs Certified

Overview

This page walks you through installing Chalk and making your first styled terminal output call. Chalk is an ESM-only Node.js library that wraps strings in ANSI escape sequences, automatically detecting your terminal's color capability at runtime — no manual escape code management required. By the end of this page you will have Chalk installed, imported, and producing color-coded output through its chainable style API.


Prerequisites

Before you begin, ensure you have:

  • Node.js ≥ 22 — Chalk's package.json declares "node": ">=22". CI tests cover Node 26 and 22.
  • An ESM-compatible project — Chalk ships no CommonJS build. Your project must be able to consume ES modules (either "type": "module" in package.json, a .mjs file extension, or an ESM-compatible bundler).
  • npm, pnpm, or yarn — any of these can install the package.

CommonJS note: On Node.js ≥ 22.12 you can require('chalk') without the ESM loader flag; the call returns the ES module namespace and you access the default export via .default. On Node.js 22.0–22.11, require('chalk') throws ERR_REQUIRE_ESM.


Quick start
  1. Install Chalk in your project:

    npm install chalk
    
  2. Create a script (e.g. hello.mjs) and import the default export:

    import chalk from 'chalk';
    
    console.log(chalk.blue('Hello world!'));
    
  3. Run the script:

    node hello.mjs
    

    You should see Hello world! printed in blue in your terminal.


Steps

Step 1 — Install the package

Run the install command for your package manager:

# npm
npm install chalk

# pnpm
pnpm add chalk

# yarn
yarn add chalk

You know this worked when chalk appears in your node_modules directory and in package.json under dependencies.


Step 2 — Import the default export

In any .js file inside an ESM project (or a .mjs file), add:

import chalk from 'chalk';

The chalk default export is a pre-configured function whose color level is auto-detected from your terminal at import time. No configuration is required for typical use.


Step 3 — Apply your first style

Call any style property as a method, passing one or more strings:

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

Chalk wraps the string in the appropriate ANSI escape sequences for your terminal and returns the result. If your terminal supports color, the text appears blue.


Step 4 — Chain styles

Style properties are chainable. Each property access returns a new, cached builder function (not the same instance), so you can combine modifiers, foreground colors, and background colors freely:

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

When two properties of the same type conflict (e.g. chalk.red.yellow), all ANSI open codes are emitted but only the last one in the chain is visually applied — chalk.red.yellow renders yellow.


Step 5 (optional) — Create an isolated instance

If you need a fixed color level independent of the host terminal — for example, to disable color in test output or force Truecolor in a specific context — construct a Chalk instance with an explicit level:

import { Chalk } from 'chalk';

const customChalk = new Chalk({ level: 0 }); // colors disabled

Valid levels are 0 (disabled), 1 (16 colors), 2 (256 colors), and 3 (Truecolor). Passing any other value throws an Error with the message The \level` should be an integer from 0 to 3`.


Examples

Basic color

import chalk from 'chalk';

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

Combining styled and plain strings

import chalk from 'chalk';

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

Chaining multiple styles

import chalk from 'chalk';

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

Passing multiple arguments (joined with spaces)

Chalk's chainable builders accept multiple string arguments and join them with a single space:

import chalk from 'chalk';

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

Nesting styles

import chalk from 'chalk';

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

Defining reusable themes

Because each property access returns a new builder function, you can store chains as named variables:

import chalk from 'chalk';

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

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

Using Truecolor and 256-color methods

import chalk from 'chalk';

console.log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));
console.log(chalk.hex('#DEADED').bold('Bold gray!'));
console.log(chalk.bgHex('#DEADED').underline('Hello, world!'));
console.log(chalk.bgRgb(15, 100, 204).inverse('Hello!'));

Chalk automatically downsamples these values to the escape format your terminal supports (e.g. if the detected level is 1, an RGB value is mapped to the nearest basic ANSI color).


Using console.log string substitution

Standard console.log substitution tokens work normally alongside Chalk:

import chalk from 'chalk';

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

Using an isolated instance with a fixed level

import { Chalk } from 'chalk';

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

CommonJS interop (Node.js ≥ 22.12 only)

On Node.js ≥ 22.12, CommonJS files can load Chalk without the ESM loader flag. Access the default export via .default:

// my-script.cjs  (Node.js ≥22.12 only)
const { default: chalk } = require('chalk');

console.log(chalk.green('Works in CJS on Node ≥22.12'));

Warning: Avoid tagged template literal syntax with core Chalk. chalk.red\text ${val}`does not interpolate correctly — the values are misplaced in the output. Usechalk.red(`text ${val}`) instead, or install the [chalk-template`](https://github.com/chalk/chalk-template) package for tagged template literal support.


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.0–22.11. The ability to require() ES modules without the loader flag was added in Node.js 22.12.

Fix: Upgrade to Node.js ≥ 22.12, or convert your file to ESM (import chalk from 'chalk').


No color in output / all text appears plain

Symptom: Chalk calls produce no color; strings are returned without ANSI codes.

Cause (a): The terminal or environment reports a color level of 0 (e.g. a non-TTY pipe, CI environment, or FORCE_COLOR=0).

Fix: Set FORCE_COLOR=1 (basic), FORCE_COLOR=2 (256-color), or FORCE_COLOR=3 (Truecolor) in your environment to override detection. Note that FORCE_COLOR takes precedence over --no-color but --color=256 and --color=16m take precedence over a non-zero numeric FORCE_COLOR.

Cause (b): You explicitly constructed new Chalk({ level: 0 }) and are using that instance.

Fix: Omit the level option or pass undefined to let Chalk detect the level automatically.


Error: The \level` should be an integer from 0 to 3`

Symptom: Constructing new Chalk({ level: n }) or assigning chalkInstance.level = n throws this error.

Cause: You passed a value that is not a safe integer between 0 and 3 (e.g. 4, 1.5, null, or a string).

Fix: Use only 0, 1, 2, or 3. To auto-detect, omit the level option entirely.


Tagged template literal produces garbled or misplaced values

Symptom: chalk.green\Hello ${name}`prints something likeHello , Sindre` — values appear after the full string rather than interpolated inline.

Cause: Core Chalk does not support tagged template literals. When used as a tag, the raw string array is coerced and values are appended after a space, not substituted at their positions.

Fix: Use a regular function call with a template literal: chalk.green(\Hello ${name}`). For full tagged template support, install the [chalk-template`](https://github.com/chalk/chalk-template) package.


Last chained color is not what appears in the terminal

Symptom: chalk.red.yellow('text') renders yellow, not red.

Cause: When conflicting styles are chained, all ANSI open codes are emitted in order. The last code in the chain is applied last and therefore wins visually. chalk.red.yellow emits the red open code followed by the yellow open code — the terminal renders yellow.

Fix: Place the style you want applied last in the chain, or remove conflicting styles.