Configuration

This page explains how to configure both chalk and degit for your specific environment and workflow. Chalk's configuration centers on color-level detection and instance creation, letting you control exactly how terminal output is styled across different streams and environments. Degit's configuration covers the options you pass when scaffolding a project — mode, caching, verbosity, and force behavior — so you can tune how templates are downloaded and applied. Understanding these options lets you integrate both tools reliably into scripts, CI pipelines, and programmatic workflows.

Before configuring BeautifulCLI tools, ensure you have the following:

• Node.js ≥ 8.0.0
• npm (bundled with Node.js)
• git (optional — required only when using --mode=git with degit for private repositories)
• chalk and degit installed in your project (see Installation below)

1. Install chalk to add terminal styling to your project:

   Copy

   npm install chalk
   

2. Install degit globally to scaffold projects from the command line:

   Copy

   npm install --global degit
   

   Or install it locally as a development dependency for programmatic use:

   Copy

   npm install --save-dev degit
   

Important: Chalk 5 is ESM-only. If you are using TypeScript or a CommonJS build tool, use Chalk 4 instead. All examples on this page assume ESM (import syntax).

Chalk configuration

Chalk automatically detects your terminal's color support level on startup. You can override this detection by setting the level property or by passing an options object to the Chalk constructor.

level property

The level property on any chalk instance controls which ANSI escape codes are emitted. Changing it on the default export affects all code that uses that instance.

import chalk from 'chalk';

// Temporarily disable all color output
chalk.level = 0;

When to use this: Only set level on the default chalk export in top-level application code. Because the default instance is shared globally, changing it in a reusable library will affect every consumer of chalk in the same process.

Creating a custom chalk instance

When you need isolated color settings — for example, in a library or when writing to a specific stream — create a new instance using the Chalk constructor:

import { Chalk } from 'chalk';

const customChalk = new Chalk({ level: 1 });

Options object

chalkStderr

chalk exports a separate pre-configured instance called chalkStderr that detects color support for stderr rather than stdout. Use this when styling output that goes to the error stream:

import { chalkStderr } from 'chalk';

console.error(chalkStderr.red('Something went wrong'));

The exported supportsColor and supportsColorStderr values expose the underlying color detection results for stdout and stderr respectively, if you need to inspect them directly.

Environment variable overrides

You can override color detection without changing code by setting environment variables before running your script:

FORCE_COLOR takes precedence over all other color-support checks.

Degit configuration

When you call degit(src, opts) programmatically, the opts object controls how the download and scaffolding process behaves.

Proxy support: Degit automatically reads the https_proxy environment variable and routes downloads through it when present.

degit.json actions file: Place a degit.json file at the root of your working directory to define post-scaffold actions (clone and remove). Degit reads and deletes this file automatically after scaffolding. See the Actions section of the degit documentation for the full schema.

Using chalk

Import the default chalk export and chain style properties onto it. Call the final property as a function, passing your string:

import chalk from 'chalk';

console.log(chalk.green('Build successful'));
console.log(chalk.bold.red('Error: file not found'));
console.log(chalk.blue.bgWhite.underline('Status'));

You can also define reusable style functions, which is the recommended pattern for keeping your code DRY:

import chalk from 'chalk';

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

console.log(error('Fatal: could not connect to database'));
console.log(warning('Deprecation: this API will be removed in v2'));
console.log(info('Listening on port 3000'));

For scripts running in CI or non-interactive environments where you want to guarantee color is disabled, create a dedicated instance:

import { Chalk } from 'chalk';

const chalk = new Chalk({ level: process.env.CI ? 0 : 3 });

Using degit

CLI usage: Run degit from your terminal, passing the repository in user/repo shorthand (defaults to GitHub) or as a full URL:

degit user/repo my-project
degit github:user/repo my-project
degit gitlab:user/repo my-project

Pass --mode=git for private repositories that require SSH access:

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

Programmatic usage: Import degit and call it with a source string and an options object. Then call .clone(destination) to download the template:

import degit from 'degit';

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

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

await emitter.clone('./my-project');

Example 1 — Basic chalk instance with auto-detected color level

The default export uses the environment's detected color level. No configuration needed for most use cases.

import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));
console.log(chalk.bold.red.bgWhite('CRITICAL'));

Expected output: The first line prints Hello world! in blue; the second prints CRITICAL in bold red text on a white background.

Example 2 — Creating a chalk instance with a fixed color level

Useful in libraries or when you need color output regardless of the environment's detection.

import { Chalk } from 'chalk';

const chalk = new Chalk({ level: 3 }); // Force Truecolor

console.log(chalk.rgb(255, 136, 0).bold('Orange alert!'));
console.log(chalk.hex('#00BFFF').underline('Deep sky blue'));
console.log(chalk.bgAnsi256(22).white('Dark green background'));

Expected output: Each line renders with the exact color specified, assuming your terminal supports Truecolor.

Example 3 — Using chalkStderr for error stream output

import { chalkStderr } from 'chalk';

process.stderr.write(chalkStderr.bold.red('ERROR: ') + 'Connection refused\n');

Expected output: ERROR: appears in bold red on stderr, followed by plain text. Color detection is based on stderr capability independently of stdout.

Example 4 — Disabling color for CI environments

import { Chalk } from 'chalk';

const chalk = new Chalk({ level: process.env.CI ? 0 : undefined });
// level: undefined → auto-detect; level: 0 → plain text

console.log(chalk.green('All tests passed'));

Expected output: In a CI environment (CI=true), prints plain All tests passed. In an interactive terminal, prints the text in green.

Example 5 — Validating style names at runtime

import { modifierNames, foregroundColorNames } from 'chalk';

console.log(modifierNames.includes('bold'));         //=> true
console.log(foregroundColorNames.includes('cyan'));  //=> true
console.log(foregroundColorNames.includes('pink'));  //=> false

Use these arrays when building a wrapper that accepts user-supplied style strings.

Example 6 — Degit with verbose logging and force overwrite

import degit from 'degit';

const emitter = degit('github:user/my-template', {
  verbose: true,
  force:   true,
});

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

emitter.on('warn', event => {
  console.warn('Warning:', event.message);
});

await emitter.clone('./output-dir');

Expected output: Verbose messages appear for each step (downloading, extracting, cache updates). The clone succeeds even if ./output-dir is not empty.

Example 7 — Degit with tar cache for offline use

import degit from 'degit';

const emitter = degit('user/my-template', {
  cache: true,  // Use ~/.degit/<user>/my-template/<hash>.tar.gz
});

await emitter.clone('./my-project');

Expected output: Degit reads from the local tarball cache instead of downloading. If the cache does not exist, the clone fails — run once online first to populate it.

Example 8 — Degit using git mode for a private repository

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

Or programmatically:

import degit from 'degit';

const emitter = degit('user/private-repo', { mode: 'git' });
await emitter.clone('./my-project');

Expected output: Degit clones via SSH, then strips the .git directory, leaving a clean snapshot of the repository in ./my-project.

No colors appear in terminal output

Symptom: All chalk output is plain text with no color or styling.

Likely cause: Chalk's auto-detected level is 0, meaning the terminal or environment does not report color support. This is common in CI systems, piped output, or terminals that don't advertise ANSI support.

Fix: Set FORCE_COLOR=3 in your environment to enable Truecolor, or create a chalk instance with an explicit level:

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

Alternatively, pass --color when running your script from the command line.

The 'level' option should be an integer from 0 to 3 error

Symptom: Chalk throws this error at startup or when constructing a custom instance.

Likely cause: You passed a non-integer or out-of-range value (e.g. level: '2' or level: 5) to the Chalk constructor options.

Fix: Ensure the level value is one of 0, 1, 2, or 3 as a JavaScript integer:

const chalk = new Chalk({ level: 2 }); // ✓ correct
const chalk = new Chalk({ level: '2' }); // ✗ wrong — string not accepted

Degit error: destination directory is not empty, aborting

Symptom: Running degit or calling .clone() fails with a DEST_NOT_EMPTY error.

Likely cause: The target directory already contains files and force is not enabled.

Fix: Pass --force on the CLI or set force: true in the options object:

degit user/repo my-project --force

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

Degit error: could not find commit hash for <ref>

Symptom: Degit throws a MISSING_REF error when you target a specific branch, tag, or commit.

Likely cause: The ref you specified does not exist on the remote repository, or the repository URL could not be reached.

Fix: Verify the branch or tag name is correct and that the repository is publicly accessible. If you are working offline, ensure the tarball cache is populated by running the command online first, then use cache: true.

Degit error: could not download <url>

Symptom: The clone fails with a COULD_NOT_DOWNLOAD error in tar mode.

Likely cause: Network connectivity issue, or the repository is private and tar mode (HTTPS) does not have access credentials.

Fix 1 — Private repository: Switch to git mode, which uses SSH:

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

Fix 2 — Proxy required: Set the https_proxy environment variable before running degit:

export https_proxy=http://your-proxy:8080
degit user/repo my-project

Chalk styles appear to bleed across newlines on macOS

Symptom: A styled string that contains a newline causes the color to continue on the next line unexpectedly.

Likely cause: This is a known macOS Terminal rendering quirk.

Fix: Chalk automatically closes and reopens style codes around line-feed characters to prevent bleed. If you are seeing this, ensure you are using the current version of chalk and that you are not manually concatenating raw ANSI codes with chalk output.