---
title: Getting Started
product: amazing-cli
doc_type: tutorial
version: main
source: git2docs (code-derived, validation-filtered)
canonical: https://git2docs.com/wabam/docs/amazing-cli/chalk/getting-started
---

# Getting Started

_Installation and first API call_

## 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:

   ```sh
   npm install chalk
   ```

2. **Create a script** (e.g. `hello.mjs`) and import the default export:

   ```js
   import chalk from 'chalk';

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

3. **Run the script**:

   ```sh
   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:

```sh
# 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:

```js
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:

```js
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:

```js
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:

```js
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

```js
import chalk from 'chalk';

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

---

### Combining styled and plain strings

```js
import chalk from 'chalk';

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

---

### Chaining multiple styles

```js
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:

```js
import chalk from 'chalk';

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

---

### Nesting styles

```js
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:

```js
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

```js
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:

```js
import chalk from 'chalk';

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

---

### Using an isolated instance with a fixed level

```js
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`:

```js
// 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. Use `chalk.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 like `Hello , 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.
