Clack Documentation

Clack provides stylish, interactive prompts for building JavaScript command-line interfaces (CLIs). It is split into two main packages depending on your needs:

• @clack/prompts: Provides opinionated, ready-to-use prompt components for quick implementation.
• @clack/core: Provides headless, unstyled prompt primitives for developers who want full control over the visual presentation.

The isCancel function detects if a user has cancelled a prompt (e.g., via CTRL + C). Use the cancel utility to display a clean cancellation message and exit the process gracefully.

import { isCancel, cancel, text } from '@clack/prompts';

const value = await text({
  message: 'What is the meaning of life?',
});

if (isCancel(value)) {
  cancel('Operation cancelled.');
  process.exit(0);
}

To create a custom text input, instantiate TextPrompt and provide a render function. Inside the render function, you can access this.userInputWithCursor to manage the visual state of the input. Use the isCancel utility to check if the user aborted the prompt (e.g., via Ctrl+C).

import { TextPrompt, isCancel } from '@clack/core';

const p = new TextPrompt({
  render() {
    return `What's your name?\n${this.userInputWithCursor}`;
  },
});

const name = await p.prompt();
if (isCancel(name)) {
  process.exit(0);
}

Use the stream API to log messages from an iterable (including async iterables), which is useful when interacting with streaming LLMs.

import { stream } from '@clack/prompts';

stream.info((function *() { yield 'Info!'; })());
stream.success((function *() { yield 'Success!'; })());
stream.step((function *() { yield 'Step!'; })());
stream.warn((function *() { yield 'Warn!'; })());
stream.error((function *() { yield 'Error!'; })());
stream.message((function *() { yield 'Hello'; yield ", World" })(), { symbol: color.cyan('~') });

The taskLog utility allows you to render the output of a sub-process continuously and clear it upon success, providing a clean interface for long-running tasks.

import { taskLog } from '@clack/prompts';

const log = taskLog({
	title: 'Running npm install'
});

for await (const line of npmInstall()) {
	log.message(line);
}

if (success) {
	log.success('Done!');
} else {
	log.error('Failed!');
}

The tasks utility allows you to execute multiple asynchronous tasks within a spinner interface.

import { tasks } from '@clack/prompts';

await tasks([
  {
    title: 'Installing via npm',
    task: async (message) => {
      // Do installation here
      return 'Installed via npm';
    },
  },
]);

Use intro to print a styled message at the start of your CLI session and outro to print a message when the session concludes.

import { intro, outro } from '@clack/prompts';

intro(`create-my-app`);
// Do stuff
outro(`You're all set!`);

Use the log utility to print styled messages to the console. Supported levels include info, success, step, warn, and error.

import { log } from '@clack/prompts';

log.info('Info!');
log.success('Success!');
log.step('Step!');
log.warn('Warn!');
log.error('Error!');
log.message('Hello, World', { symbol: color.cyan('~') });

When using the DatePrompt (or the corresponding date prompt function in @clack/prompts), you can provide a DateOptions object to control its behavior.

Key options include:

• format: A DateFormat string ('YMD', 'MDY', or 'DMY') to define the order of year, month, and day.
• locale: A string representing a BCP 47 language tag. If provided, the prompt will attempt to detect the appropriate date format and separator using Intl.DateTimeFormat.
• separator: A custom string used to separate date segments (e.g., /, -). If format is provided, this defaults to / if not specified.
• defaultValue: The Date object returned if the user cancels or provides an invalid input.
• initialValue: The Date object used to pre-fill the prompt segments.
• minDate: The earliest valid Date allowed.
• maxDate: The latest valid Date allowed.