Installation

This page walks you through installing both BeautifulCLI tools — chalk and degit — using npm. Once installed, chalk is available as a library you import into your Node.js scripts to style terminal output, while degit is available as a global CLI command you run to scaffold new projects from git repository templates. Getting both tools in place is the foundation for every other workflow in this documentation.

Before you begin, make sure the following are available in your environment:

• Node.js ≥ 8.0.0 (chalk 5 requires ^12.17.0 || ^14.13 || >=16.0.0 for full ESM support — see the note in Installation)
• npm (bundled with Node.js)
• git (optional — only required when using degit with --mode=git for private repositories)

To verify your Node.js and npm versions, run:

node --version
npm --version

Install chalk and degit separately — chalk is a project dependency you save to your package, while degit is a global CLI tool.

1. Install chalk as a project dependency

Run this command inside your project directory:

npm install chalk

This adds chalk to your node_modules and records it in your package.json dependencies.

Important — ESM vs CommonJS: Chalk 5 (the current release, 5.6.2) is ESM-only. Your project must either use "type": "module" in its package.json, or use a dynamic import() call. If you are using TypeScript or a CommonJS build tool and cannot yet consume ESM, install Chalk 4 instead:

Copy

npm install chalk@4

2. Install degit as a global CLI tool

npm install -g degit

The -g flag makes the degit command available system-wide, so you can run it from any directory without a local install.

3. Verify both installations

Confirm chalk is installed in your project:

npm list chalk

Confirm the degit binary is accessible:

degit --help

If degit --help prints usage information, both tools are ready to use.

Neither tool requires configuration to get started, but both expose options that change their behaviour in important ways.

chalk — chalk.level

Chalk automatically detects your terminal's color support at startup and sets an internal level value accordingly. You can read or override this property when you need deterministic output:

Overriding chalk.level applies globally to every chalk call in the same process. For reusable modules, create a scoped instance instead so you do not affect other consumers:

import { Chalk } from 'chalk';

const customChalk = new Chalk({ level: 0 }); // colors off for this instance

You can also control color support from outside the process with environment variables, which take precedence over all other checks:

The --color and --no-color CLI flags also control this when they are passed to your script.

degit — download mode

Degit defaults to tar mode, which fetches a compressed snapshot over HTTPS and is the fastest option. Pass --mode=git to switch to SSH-based cloning, which is required for private repositories:

Degit also respects the https_proxy environment variable if your network requires a proxy for outbound HTTPS traffic.

Using chalk in your scripts

Import chalk and chain style methods to produce colored terminal output. You can combine colors, background colors, and text modifiers in a single expression:

import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));
console.log(chalk.bold.red('Error: something went wrong'));
console.log(chalk.bgGreen.black(' SUCCESS '));

Define reusable style shortcuts to keep your code consistent across a project:

import chalk from 'chalk';

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

console.log(error('Build failed'));
console.log(warning('Deprecated API in use'));
console.log(info('Listening on port 3000'));

Using degit from the CLI

Scaffold a new project by running degit with any public GitHub, GitLab, BitBucket, or Sourcehut repository as the argument. The second argument is the destination directory (defaults to the current directory if omitted):

# Scaffold into a new folder called my-app
degit user/repo my-app

# Scaffold the current directory
degit user/repo

Point to a specific branch, tag, or commit hash using the # separator:

degit user/repo#dev          # branch
degit user/repo#v1.2.3       # release tag
degit user/repo#1234abcd     # commit hash

Download only a subdirectory of a repository:

degit user/repo/packages/my-template my-app

Example 1 — Basic chalk colors

Apply foreground and background colors to log messages:

import chalk from 'chalk';

console.log(chalk.green('Build complete'));
console.log(chalk.red('Build failed'));
console.log(chalk.yellow('Warning: 3 deprecations found'));
console.log(chalk.blue.bgWhite(' INFO ') + ' Server started');

Expected terminal output: Each string is printed in the corresponding color, with the INFO label displayed in blue text on a white background.

Example 2 — RGB and hex colors with chalk

Use extended color modes for precise brand or design colors:

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!'));

Expected terminal output: Each line renders with the specified RGB or hex color. If the terminal does not support truecolor (level 3), chalk automatically downsamples to the closest supported ANSI value.

Example 3 — Scaffold a project with degit

Download the latest snapshot of a GitHub repository into a new folder:

degit user/my-template my-project
cd my-project

Expected output: The template files appear in my-project/ with no .git folder. A cached tarball is stored at ~/.degit/user/my-template/<commithash>.tar.gz for offline reuse.

Example 4 — Scaffold from a specific branch

degit user/my-template#staging my-project

Expected output: Degit resolves the latest commit on the staging branch, downloads its snapshot, and extracts it into my-project/.

Example 5 — Use degit programmatically

Call degit from inside a Node.js script for automated scaffolding workflows:

const degit = require('degit');

const emitter = degit('user/repo', {
  cache: true,
  force: true,
  verbose: true,
});

emitter.on('info', info => {
  console.log(info.message);
});

emitter.clone('path/to/dest').then(() => {
  console.log('done');
});

Expected output: Progress messages are logged via the info event, and done is printed once the snapshot has been extracted to path/to/dest.

chalk produces no colors in the terminal

Symptom: All chalk.* calls print plain text with no color.

Likely cause: Chalk detected that your terminal does not support color, setting chalk.level to 0. This can happen in CI environments, piped output, or terminals that do not advertise color support.

Fix: Force a color level with an environment variable before running your script:

FORCE_COLOR=3 node your-script.js

Or pass the --color flag if your script accepts it. Do not permanently hard-code chalk.level in shared library code — use a scoped new Chalk({ level: 3 }) instance instead.

chalk import fails with ERR_REQUIRE_ESM

Symptom: Running require('chalk') throws Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

Likely cause: Chalk 5 is ESM-only. Your project or a dependency is loading it via CommonJS require().

Fix: Either migrate your project to ESM ("type": "module" in package.json and import syntax), or downgrade to Chalk 4 which supports CommonJS:

npm install chalk@4

degit command not found after installation

Symptom: Running degit user/repo returns command not found or degit is not recognized.

Likely cause: The global npm binary directory is not on your PATH, or the -g flag was omitted.

Fix: Re-install with the global flag and verify your PATH:

npm install -g degit
npm bin -g   # prints the global bin directory; add it to PATH if missing

degit fails on a private repository

Symptom: Degit exits with a network or authentication error when scaffolding a private repo.

Likely cause: The default tar mode fetches over HTTPS and does not support private repository authentication.

Fix: Use --mode=git, which clones over SSH. Make sure your SSH key is configured for the host:

degit user/private-repo my-project --mode=git

degit downloads stale files instead of the latest commit

Symptom: The scaffolded project does not reflect recent changes to the template repository.

Likely cause: Degit found a cached tarball at ~/.degit/<user>/<repo>/<commithash>.tar.gz and reused it.

Fix: This only happens when the commit hash has not changed. If the remote branch has been force-pushed or you want to bypass the cache, delete the relevant entry from ~/.degit/ and re-run the command. Under normal circumstances (new commits produce new hashes), degit will always fetch the latest snapshot.