cli

Terminal styling, output, and interactive prompts for Node, Deno, and Bun.

Browser bundles can import this package, but accessing any CLI utility throws because terminals and standard streams are not available through the browser entry.

import cli from "@rcompat/cli";

The default CLI utility aggregate.

cli.bg#

Background ANSI colors.

cli.bg: {
  black(message: string): string;
  blue(message: string): string;
  cyan(message: string): string;
  gray(message: string): string;
  green(message: string): string;
  magenta(message: string): string;
  red(message: string): string;
  white(message: string): string;
  yellow(message: string): string;
};

cli.fg#

Foreground ANSI colors and text styles.

cli.fg: {
  black(message: string): string;
  blue(message: string): string;
  bold(message: string): string;
  cyan(message: string): string;
  dim(message: string): string;
  gray(message: string): string;
  green(message: string): string;
  inverse(message: string): string;
  magenta(message: string): string;
  red(message: string): string;
  white(message: string): string;
  yellow(message: string): string;
};

cli.print()#

Writes messages to standard output, separated by spaces, without appending a newline.

Parameters

• messages — Text fragments to write.

Returns: Whether the standard-output stream can accept more data.

cli.print(...messages: string[]): boolean;

cli.prompt#

Interactive prompt and prompt-output utilities.

Prompt methods#

cli.prompt.cancel()#

Writes a styled cancellation message and returns the cancellation symbol.

Parameters

• message — Message to write.

Returns: The symbol recognized by cli.prompt.isCancel.

cli.prompt.cancel(message?: string): CancelSymbol;

cli.prompt.confirm()#

Prompts for a yes-or-no response.

Parameters

• args — Message and optional initial response.

Returns: The submitted boolean or the cancellation symbol.

cli.prompt.confirm(
  args: ConfirmOptions,
): Promise<boolean | CancelSymbol>;

cli.prompt.intro()#

Writes a styled introductory message when one is provided.

Parameters

• message — Message to write.

cli.prompt.intro(message?: string): void;

cli.prompt.isCancel()#

Tests whether a prompt result is the cancellation symbol.

Parameters

• value — Prompt result to test.

cli.prompt.isCancel(value: unknown): value is CancelSymbol;

cli.prompt.multiselect()#

Prompts for one or more comma-separated numbered options.

Type parameters

• T — Option value type.

Parameters

• args — Message, options, and initial option indexes.

Returns: Selected values in input order, without duplicates.

cli.prompt.multiselect<T>(
  args: MultiselectOptions<T>,
): Promise<T[]>;

cli.prompt.outro()#

Writes a styled completion message when one is provided.

Parameters

• message — Message to write.

cli.prompt.outro(message?: string): void;

cli.prompt.readline()#

Reads one line from standard input.

Returns: The line without its newline, or null on interruption or end-of-input.

cli.prompt.readline(): Promise<null | string>;

cli.prompt.select()#

Prompts for one numbered option.

Type parameters

• T — Option value type.

Parameters

• args — Message, options, and initial option index.

Returns: The selected option value. End-of-input selects the initial option.

cli.prompt.select<T>(args: SelectOptions<T>): Promise<T>;

Example

const runtime = await cli.prompt.select({
  message: "Choose a runtime",
  options: [
    { label: "Node", value: "node" },
    { label: "Deno", value: "deno" },
  ],
});
// runtime is "node" or "deno"

cli.prompt.spinner()#

Creates a terminal progress spinner.

Non-interactive output uses plain start and stop messages.

Returns: Controls for starting, updating, and stopping the spinner.

cli.prompt.spinner(): Spinner;

cli.prompt.text()#

Prompts for text until validation succeeds or input is cancelled.

Parameters

• args — Message, initial value, and optional validator.

Returns: The submitted text or the cancellation symbol.

cli.prompt.text(
  args: TextOptions,
): Promise<CancelSymbol | string>;

Supporting contracts#

These contracts describe the default aggregate but are not named root exports.

CancelSymbol#

Symbol returned when a cancellable prompt is interrupted.

type CancelSymbol = symbol;

ConfirmOptions#

Options for cli.prompt.confirm.

type ConfirmOptions = {
  // Response used when the submitted line is empty.
  initial?: boolean;
  // Prompt message.
  message: string;
};

MultiselectOptions#

Options for cli.prompt.multiselect.

type MultiselectOptions<T> = {
  // Zero-based option indexes selected by default.
  initial?: number[];
  // Prompt message.
  message: string;
  // Available labeled values.
  options: Array<SelectOption<T>>;
};

SelectOption#

One labeled selection value.

type SelectOption<T> = {
  // Label shown to the user.
  label: string;
  // Value returned when selected.
  value: T;
};

SelectOptions#

Options for cli.prompt.select.

type SelectOptions<T> = {
  // Zero-based option selected on end-of-input.
  // Default: `0`
  initial?: number;
  // Prompt message.
  message: string;
  // Available labeled values.
  options: Array<SelectOption<T>>;
};

Spinner#

Controls for a terminal progress spinner.

interface Spinner {
  // Updates the message shown by an active spinner.
  message(text: string): void;
  // Starts the spinner with a message.
  start(text: string): void;
  // Stops the spinner and optionally replaces its final message.
  stop(text?: string): void;
}

TextOptions#

Options for cli.prompt.text.

type TextOptions = {
  // Value used when the submitted line is empty.
  initial?: string;
  // Prompt message.
  message: string;
  // Returns an error message to reject input, or nothing to accept it.
  validate?: (input: string) => Promise<string | void> | string | void;
};