---
title: API Reference
product: amazing-cli
doc_type: api_reference
version: main
source: git2docs (code-derived, validation-filtered)
canonical: https://git2docs.com/wabam/docs/amazing-cli/chalk/api-reference
---

# API Reference

_Complete API documentation for all public classes, functions, and types_

## Description

Chalk exposes a chainable style-builder API for wrapping strings in ANSI escape sequences. Import the default export for immediate use with auto-detected color support, or construct an isolated `Chalk` instance when you need explicit control over the color level — for example, when writing to a non-TTY stream or inside a reusable module. Every style property access and color method call returns a new, cached builder function; calling that builder with one or more string arguments produces the final styled string.

## Parameters

### `new Chalk(options?)`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `options` | `Options` | No | Configuration object for the new instance. |
| `options.level` | `0 \| 1 \| 2 \| 3 \| undefined` | No | Color support level. `0` disables all colors, `1` enables basic 16-color support, `2` enables 256-color support, `3` enables Truecolor (16 million colors). Omit or pass `undefined` to auto-detect from the environment. |

---

### Style builder call signature

Every `ChalkInstance` (including the default export) is itself a callable. Once you have built up a chain of styles, call the final builder:

| Parameter | Type | Required | Description |
|---|---|---|---|
| `...text` | `unknown[]` | Yes (at least one) | One or more values to style. Multiple arguments are joined with a single space. |

---

### Dynamic color methods

#### `rgb(red, green, blue)` / `bgRgb(red, green, blue)` / `underlineRgb(red, green, blue)`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `red` | `number` | Yes | Red channel, 0–255. |
| `green` | `number` | Yes | Green channel, 0–255. |
| `blue` | `number` | Yes | Blue channel, 0–255. |

#### `hex(color)` / `bgHex(color)` / `underlineHex(color)`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `color` | `string` | Yes | CSS-style hex string, e.g. `'#DEADED'`. |

#### `ansi256(index)` / `bgAnsi256(index)` / `underlineAnsi256(index)`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `index` | `number` | Yes | 8-bit color index, 0–255. |

## Errors

| Error | Condition |
|---|---|
| `Error: The \`level\` should be an integer from 0 to 3` | Thrown by `new Chalk({ level })` when `level` is not `undefined` and is not a safe integer in the range 0–3. |
| `Error: The \`level\` should be an integer from 0 to 3` | Thrown by the `level` setter on any `ChalkInstance` (including the default export) when you assign a value that is not a safe integer in the range 0–3. |
| `ERR_REQUIRE_ESM` | Thrown by Node.js itself when you call `require('chalk')` on a Node.js release earlier than 22.12. On Node.js ≥22.12 `require('chalk')` succeeds and returns the ES module namespace; access the default export via `.default`. |

## Examples

### Basic styling

Import the default export and chain styles.

```js
import chalk from 'chalk';

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

---

### Chaining multiple styles

```js
import chalk from 'chalk';

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

---

### Multiple arguments (joined with spaces)

```js
import chalk from 'chalk';

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

---

### Nesting styled strings

```js
import chalk from 'chalk';

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

---

### Defining reusable theme helpers

Capture a partially-applied builder and reuse it like a function.

```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 `console.log` string substitution

```js
import chalk from 'chalk';

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

---

### RGB and hex colors

```js
import chalk from 'chalk';

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

---

### Background and underline color variants

```js
import chalk from 'chalk';

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

// Underline colors only show when an underline style is also applied
console.log(chalk.underlineHex('#DEADED').underlineCurly('Hello, world!'));
console.log(chalk.underlineRgb(15, 100, 204).underline('Hello!'));
```

---

### 8-bit (ansi256) colors

```js
import chalk from 'chalk';

console.log(chalk.ansi256(201)('Purple-ish text'));
console.log(chalk.bgAnsi256(194)('Honeydew, more or less'));
```

---

### Creating an isolated `Chalk` instance

Use `new Chalk({ level })` in a reusable module so you do not globally mutate the shared default instance.

```js
import { Chalk } from 'chalk';

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

const truecolorChalk = new Chalk({ level: 3 });
console.log(truecolorChalk.hex('#FF8800').bold('Orange!'));
```

---

### Configuring `level` after construction

```js
import chalk from 'chalk';

chalk.level = 1; // Downgrade to basic 16-color support for this process
```

---

### Inspecting color support at runtime

```js
import { supportsColor, supportsColorStderr } from 'chalk';

if (supportsColor) {
  console.log(`stdout color level: ${supportsColor.level}`);
}

if (supportsColorStderr) {
  console.log(`stderr color level: ${supportsColorStderr.level}`);
}
```

---

### Writing to stderr with `chalkStderr`

```js
import { chalkStderr } from 'chalk';

process.stderr.write(chalkStderr.red('Something went wrong\n'));
```

---

### Validating style names at runtime

```js
import { modifierNames, foregroundColorNames } from 'chalk';

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

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

---

### CommonJS interop (Node.js ≥22.12 only)

```js
// Works only on Node.js >=22.12; throws ERR_REQUIRE_ESM on earlier 22.x releases.
const chalkModule = require('chalk');
const chalk = chalkModule.default;

console.log(chalk.green('CommonJS interop'));
```

---

### Tagged template literals — use `chalk-template` instead

Core chalk does **not** support tagged template literal interpolation. The following produces incorrect output:

```js
// ❌ Wrong — values are misplaced, not interpolated correctly
chalk.green`Hello ${name}`;
```

Use the `chalk-template` package for tagged template literal support:

```js
// ✅ Correct — install chalk-template separately
import chalkTemplate from 'chalk-template';

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

## Notes

### Builder functions are cached, not shared

Accessing a style property such as `chalk.red` returns a **new** builder function the first time, then caches it on the parent builder. It never returns `this`. This means `new Chalk({ level: 1 }).red === instance` is `false`. Each link in a chain is a distinct function object.

---

### Chaining conflicting styles

When you chain more than one style of the same type (for example, two foreground colors), all ANSI open codes are emitted in the output string. Because later codes open after earlier ones, only the **last** conflicting style is visually applied. For example, `chalk.yellow.red` renders red text, while `chalk.red.yellow` renders yellow text.

---

### Multiple arguments vs. template literals

Calling `chalk.red('a', 'b', 'c')` joins the arguments with spaces: the result is the same as `chalk.red('a b c')`. This is entirely different from tagged template literal syntax — which core chalk does not support. To interpolate values in a template, call the builder as a regular function inside the template expression:

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

---

### Environment-variable overrides

The vendored `supports-color` module reads several environment signals in priority order:

- **`FORCE_COLOR`** — A numeric value (`0`–`3`) sets the level directly, capped at 3. `FORCE_COLOR=true` (or an empty string) enables color at level 1 or above. `FORCE_COLOR` **overrides** `--no-color`; it does not override `--color=256` or `--color=16m`.
- **`--color=16m`** and **`--color=256`** CLI flags — Enable Truecolor (level 3) and 256-color (level 2) respectively, and take precedence over a non-zero numeric `FORCE_COLOR`.
- **`--color`** and **`--no-color`** CLI flags — Enable or disable color at the detected terminal level. `FORCE_COLOR` overrides `--no-color`.
- **`TERM`, `COLORTERM`, and CI-related variables** — Inspected for additional color-level hints.

Chalk does **not** read or respect `NO_COLOR`.

---

### Underline colors require an underline style

Underline color methods (`underlineRed`, `underlineHex`, etc.) only produce visible output when an underline style modifier (`underline`, `underlineCurly`, `underlineDotted`, etc.) is also present in the chain. At level 1, underline colors are downsampled to the first 16 palette entries rather than to a basic color code.

---

### Color downsampling

When a terminal supports fewer colors than a method requests, chalk automatically downsamples. For example, `chalk.ansi256(196)` becomes ANSI escape `91` (bright red) at level 1, and `chalk.bgAnsi256(196)` becomes `101` at level 1.

---

### Browser environments

In non-Node runtimes (bundled browser code), chalk resolves `source/vendor/supports-color/browser.js` via the `default` export condition in `package.json`. That module inspects the Chromium brand version: a brand version above 93 receives level 3; any other Chrome or Chromium user agent receives level 1; a non-Chromium browser or an environment with no `navigator` object receives level 0. Since Chrome 69, ANSI escape codes are natively supported in the developer console.

---

### No runtime dependencies

Chalk has no npm dependencies. `ansi-styles` and `supports-color` are vendored under `source/vendor/` and imported internally via the `#ansi-styles` and `#supports-color` import-map aliases. Your dependency graph is not affected.

---

### Deprecated exports

The following exports exist for backward compatibility and will be removed in a future major version. Prefer the non-deprecated equivalents.

| Deprecated export | Preferred replacement |
|---|---|
| `modifiers` | `modifierNames` |
| `foregroundColors` | `foregroundColorNames` |
| `backgroundColors` | `backgroundColorNames` |
| `colors` | `colorNames` |
| Type `Modifiers` | Type `ModifierName` |
| Type `ForegroundColor` | Type `ForegroundColorName` |
| Type `BackgroundColor` | Type `BackgroundColorName` |
| Type `Color` | Type `ColorName` |
