cli

Terminal colors, output, and interactive prompts for JavaScript runtimes.

What is @rcompat/cli?#

@rcompat/cli provides one default export containing foreground and background colors, direct output, and common interactive prompts. It works consistently in Node, Bun, and Deno. CLI utilities throw when accessed in a browser.

Installation#

npm install @rcompat/cli

pnpm add @rcompat/cli

yarn add @rcompat/cli

bun add @rcompat/cli

Usage#

Colors#

Use cli.fg for foreground colors and text styles, and cli.bg for background colors:

import cli from "@rcompat/cli";

console.log(cli.fg.red("Error: something went wrong"));
console.log(cli.fg.green("Success!"));
console.log(cli.fg.bold(cli.fg.blue("Important information")));
console.log(cli.bg.yellow(cli.fg.black("Warning")));

Foreground styles include black, blue, bold, cyan, dim, gray, green, inverse, magenta, red, white, and yellow. Background colors include the same colors except for the text-only styles bold, dim, and inverse.

Output#

cli.print writes messages to standard output, separated by spaces, without adding a newline:

import cli from "@rcompat/cli";

cli.print("Loading", "...");
cli.print("\n");

Text and confirmation prompts#

Prompt methods live under cli.prompt. Text and confirmation prompts return a cancel symbol on end-of-input or interruption; use isCancel to distinguish it from a submitted value.

import cli from "@rcompat/cli";

const name = await cli.prompt.text({
  message: "What is your name?",
  initial: "Anonymous",
  validate: value => value.length < 2
    ? "Name must be at least 2 characters"
    : undefined,
});

if (cli.prompt.isCancel(name)) {
  cli.prompt.cancel("Setup cancelled");
} else {
  const proceed = await cli.prompt.confirm({
    message: `Continue as ${name}?`,
    initial: true,
  });

  if (proceed === true) cli.prompt.outro("Setup complete");
}

Selection prompts#

import cli from "@rcompat/cli";

const runtime = await cli.prompt.select({
  message: "Select a runtime",
  options: [
    { label: "Node", value: "node" },
    { label: "Bun", value: "bun" },
    { label: "Deno", value: "deno" },
  ],
  initial: 0,
});

const features = await cli.prompt.multiselect({
  message: "Select features",
  options: [
    { label: "TypeScript", value: "typescript" },
    { label: "Linting", value: "lint" },
    { label: "Testing", value: "test" },
  ],
  initial: [0, 1],
});

console.log(runtime, features);

Spinner#

import cli from "@rcompat/cli";

const spinner = cli.prompt.spinner();
spinner.start("Installing dependencies");

await new Promise(resolve => setTimeout(resolve, 1000));

spinner.stop("Dependencies installed");

The spinner animates on an interactive terminal and falls back to plain output when standard output is not a TTY.

API reference#

cli.fg and cli.bg#

Each property is a function that wraps a string in the corresponding ANSI color or style sequence.

cli.fg.red(message: string): string;
cli.fg.bold(message: string): string;
cli.bg.blue(message: string): string;

cli.print(...messages)#

Writes string messages to standard output, joined with spaces.

cli.prompt.text(options)#

Reads a string. Supports message, optional initial, and an optional sync or async validate callback.

cli.prompt.confirm(options)#

Reads a yes/no response. Supports message and an optional boolean initial value.

cli.prompt.select(options)#

Selects one { label, value } option and returns its value.

cli.prompt.multiselect(options)#

Selects one or more { label, value } options and returns their values. The optional initial array contains zero-based option indexes.

cli.prompt.spinner()#

Returns an object with start(message), message(text), and stop(message?) methods.

Other prompt helpers#

• cli.prompt.intro(message?) prints an introductory message.
• cli.prompt.outro(message?) prints a completion message.
• cli.prompt.cancel(message?) prints a cancellation message and returns the cancel symbol.
• cli.prompt.isCancel(value) identifies the cancel symbol.
• cli.prompt.readline() reads one line from standard input.

Runtime compatibility#

License#

MIT

Contributing#

See CONTRIBUTING.md in the repository root.