Getting Started

This page walks you through installing BeautifulCLI's two core tools — degit and chalk — and making your first API call with each. By the end, you will have scaffolded a new project from a remote git repository and printed styled text to your terminal, giving you a working foundation for building polished command-line experiences.

Before you begin, make sure you have the following installed:

• Node.js ≥ 8.0.0 — both tools require it; degit specifically relies on async/await support introduced in Node 8
• npm — used to install both packages
• git — optional; only required if you plan to use --mode=git for private repository access

Verify your Node.js version by running:

node --version

If the version shown is below v8.0.0, update Node.js before continuing.

The minimal path to a working setup:

1. Install degit globally so the degit command is available in your shell:

   Copy

   npm install -g degit
   

2. Install chalk as a dependency in your project:

   Copy

   npm install chalk
   

3. Scaffold a new project from any public GitHub repository:

   Copy

   degit user/repo my-new-project
   

4. In your Node.js script, import chalk and print styled output:

   Copy

   import chalk from 'chalk';
   console.log(chalk.green('Setup complete!'));
   

If you see a green "Setup complete!" message in your terminal, both tools are working correctly.

Step 1 — Install degit globally

Install degit as a global CLI tool so you can run it from any directory:

npm install -g degit

Success: Running degit --help prints the available options without an error.

Step 2 — Scaffold your first project

Run degit with a user/repo argument (and optionally a destination folder name) to download the repository's files as a snapshot:

degit user/repo my-new-project

Degit fetches the latest commit on the default branch, stores a compressed snapshot at ~/.degit/user/repo/<commithash>.tar.gz, and extracts the files into my-new-project/ — without any git history.

Success: The my-new-project/ directory exists and contains the template's files. There is no .git folder inside it.

Step 3 — Navigate into your new project

cd my-new-project

Initialize a fresh npm project if the template does not already include a package.json:

npm init -y

Step 4 — Install chalk

Add chalk as a dependency of your project:

npm install chalk

Success: chalk appears in your node_modules/ folder and is listed under dependencies in package.json.

Note: Chalk 5 is ESM-only. If your project uses CommonJS (require()) or a TypeScript build tool, install Chalk 4 instead: npm install chalk@4.

Step 5 — Make your first chalk API call

Create a file named index.js (or index.mjs for ESM) and add the following:

import chalk from 'chalk';

console.log(chalk.blue('Hello from BeautifulCLI!'));
console.log(chalk.bold.green('Project scaffolded successfully.'));

Run it:

node index.js

Success: Your terminal displays "Hello from BeautifulCLI!" in blue and "Project scaffolded successfully." in bold green.

Example 1 — Scaffold from GitHub (default branch)

Download the files from user/repo on GitHub into a new folder called my-app:

degit user/repo my-app

Expected output:

> cloned user/repo#<commithash> to my-app

The folder my-app/ now contains the repository's files with no git history attached.

Example 2 — Scaffold from an alternative git host

Degit supports GitHub, GitLab, BitBucket, and Sourcehut. Use a host prefix to be explicit:

# GitLab
degit gitlab:user/repo my-app

# BitBucket
degit bitbucket:user/repo my-app

# Sourcehut
degit git.sr.ht/user/repo my-app

Example 3 — Print a styled message with chalk

import chalk from 'chalk';

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

Expected terminal output:

Hello world!

(The text "Hello world!" is rendered in blue.)

Example 4 — Chain multiple styles

Combine colors, backgrounds, and modifiers in a single expression:

import chalk from 'chalk';

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

Expected terminal output:

Hello world!

(Bold white text on a red background, in blue — later styles in the chain take precedence for conflicts.)

Example 5 — Mix styled and unstyled strings

import chalk from 'chalk';

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

Expected terminal output:

Hello World!

("Hello" is blue, " World" is unstyled, "!" is red.)

Example 6 — Define reusable style themes

Create named style constants to keep your output consistent across your CLI:

import chalk from 'chalk';

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

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

Expected terminal output:

Error!
Warning!

("Error!" in bold red; "Warning!" in orange.)

Example 7 — Use degit programmatically inside a Node.js script

For scripted or automated scaffolding workflows, call degit from JavaScript:

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 terminal output:

> cloned user/repo#<commithash> to path/to/dest
done

degit command not found after installation

Symptom: Running degit user/repo prints command not found or similar.

Likely cause: degit was not installed globally, or your shell's PATH does not include npm's global binary directory.

Fix:

1. Confirm you used the -g flag: npm install -g degit
2. Find the global bin directory with npm bin -g and ensure it is on your PATH.
3. Restart your terminal session after installing.

chalk shows no color output

Symptom: Text printed with chalk appears unstyled or plain white in your terminal.

Likely cause: Chalk auto-detects color support and disables colors when it cannot detect a color-capable terminal (for example, when output is piped or in CI environments).

Fix:

• Force color on by setting the environment variable before running your script:
  Copy

  FORCE_COLOR=1 node index.js
  

• Or set chalk.level in your code (affects all chalk consumers globally — use a custom instance instead for library code):
  Copy

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

SyntaxError: Cannot use import statement in a module when using chalk

Symptom: Node.js throws a syntax error on import chalk from 'chalk';.

Likely cause: Chalk 5 is ESM-only. Your project is configured as CommonJS, or you are running a .js file without "type": "module" in package.json.

Fix (option A): Add "type": "module" to your package.json to enable ESM.

Fix (option B): Install Chalk 4, which supports CommonJS require():

npm install chalk@4

Then use:

const chalk = require('chalk');

degit fails to download a private repository

Symptom: degit exits with an authentication or permission error when targeting a private repo.

Likely cause: The default tar mode fetches over HTTPS without authentication and cannot access private repositories.

Fix: Use --mode=git to switch to SSH-based cloning:

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

Ensure your SSH key is configured and authorized for the target host before running this command.

degit does not pick up recent commits

Symptom: The scaffolded files appear outdated even after a new commit was pushed to the repository.

Likely cause: Degit reuses a cached tarball from ~/.degit/<user>/<repo>/ if one already exists for the resolved commit hash.

Fix: Pass --force to bypass the cache and fetch a fresh snapshot:

degit user/repo my-project --force