or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-workflows.mdcancellation-handling.mdindex.mdinteractive-prompts.mdlogging-system.mdprogress-indicators.mdselection-prompts.mdsession-management.mdsettings-configuration.md
tile.json

tessl/npm-clack--prompts

Effortlessly build beautiful command-line apps - an opinionated, pre-styled wrapper around @clack/core

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@clack/prompts@0.11.x

To install, run

npx @tessl/cli install tessl/npm-clack--prompts@0.11.0

index.mddocs/

@clack/prompts

@clack/prompts is a comprehensive command-line interface (CLI) prompting library that enables developers to create beautiful, interactive terminal applications with minimal effort. It offers a rich set of pre-styled UI components including text input, confirmation dialogs, single and multi-select menus, and loading spinners, all built with a clean, modern aesthetic that's 80% smaller than alternative solutions.

Package Information

  • Package Name: @clack/prompts
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @clack/prompts

Core Imports

import {
  text, password, confirm, select, multiselect, selectKey, groupMultiselect,
  intro, outro, cancel, note, log, spinner,
  isCancel, group, tasks, updateSettings
} from "@clack/prompts";

For CommonJS:

const {
  text, password, confirm, select, multiselect, selectKey, groupMultiselect,
  intro, outro, cancel, note, log, spinner,
  isCancel, group, tasks, updateSettings
} = require("@clack/prompts");

Basic Usage

import { intro, outro, text, confirm, isCancel, cancel } from "@clack/prompts";

intro("Welcome to my CLI");

const name = await text({
  message: "What's your name?",
  placeholder: "Enter your name",
  validate: (value) => {
    if (value.length === 0) return "Name is required!";
  }
});

if (isCancel(name)) {
  cancel("Operation cancelled.");
  process.exit(0);
}

const shouldContinue = await confirm({
  message: "Do you want to continue?",
});

if (isCancel(shouldContinue)) {
  cancel("Operation cancelled.");
  process.exit(0);
}

outro("Done!");

Architecture

@clack/prompts is built around several key components:

  • Core Prompts: Interactive input components (text, password, confirm, select, multiselect) with built-in validation and styling
  • Session Management: Flow control utilities (intro, outro, cancel) for managing prompt sessions
  • Advanced Features: Complex workflows with group for multi-prompt sequences and tasks for long-running operations
  • Logging System: Comprehensive logging utilities (log, stream) for different message types and real-time output
  • Progress Indicators: Visual feedback components (spinner, note) for enhanced user experience
  • Cancellation Handling: Built-in support for graceful cancellation detection with isCancel

Capabilities

Interactive Prompts

Core input components for gathering user information with built-in validation, styling, and cancellation support. Perfect for configuration scripts, CLI wizards, and interactive tools.

function text(opts: TextOptions): Promise<string | symbol>;
function password(opts: PasswordOptions): Promise<string | symbol>;
function confirm(opts: ConfirmOptions): Promise<boolean | symbol>;

Interactive Prompts

Selection Prompts

Menu-driven selection components for choosing from predefined options with keyboard navigation, hints, and grouping support.

function select<Value>(opts: SelectOptions<Value>): Promise<Value | symbol>;
function selectKey<Value extends string>(opts: SelectOptions<Value>): Promise<Value | symbol>;
function multiselect<Value>(opts: MultiSelectOptions<Value>): Promise<Value[] | symbol>;
function groupMultiselect<Value>(opts: GroupMultiSelectOptions<Value>): Promise<Value[] | symbol>;

Selection Prompts

Session Management

Flow control utilities for managing prompt sessions with consistent visual styling and proper session boundaries.

function intro(title?: string): void;
function outro(message?: string): void;
function cancel(message?: string): void;
function note(message?: string, title?: string): void;

Session Management

Advanced Workflows

Complex prompt orchestration with grouped prompts, task execution, and shared state management for sophisticated CLI applications.

function group<T>(
  prompts: PromptGroup<T>,
  opts?: PromptGroupOptions<T>
): Promise<Prettify<PromptGroupAwaitedReturn<T>>>;

function tasks(tasks: Task[]): Promise<void>;

Advanced Workflows

Progress Indicators

Visual feedback components for long-running operations, including customizable spinners and progress messaging.

function spinner(options?: SpinnerOptions): {
  start: (msg?: string) => void;
  stop: (msg?: string, code?: number) => void;
  message: (msg?: string) => void;
};

Progress Indicators

Logging System

Comprehensive logging utilities supporting both static and streaming output with different message types and custom symbols.

interface LogSystem {
  message: (message?: string, options?: LogMessageOptions) => void;
  info: (message: string) => void;
  success: (message: string) => void;
  step: (message: string) => void;
  warn: (message: string) => void;
  warning: (message: string) => void;
  error: (message: string) => void;
}

interface StreamSystem {
  message: (iterable: Iterable<string> | AsyncIterable<string>, options?: LogMessageOptions) => Promise<void>;
  info: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
  success: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
  step: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
  warn: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
  warning: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
  error: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;
}

Logging System

Cancellation Handling

Utilities for graceful handling of user cancellation across all prompt types with consistent behavior.

function isCancel(value: any): boolean;

Cancellation Handling

Settings Configuration

Global configuration utilities for customizing key bindings and interaction behavior across all prompts.

function updateSettings(updates: ClackSettings): void;

interface ClackSettings {
  aliases: Record<string, Action>;
}

type Action = 'up' | 'down' | 'left' | 'right' | 'space' | 'enter' | 'cancel';

Settings Configuration

Core Types

interface TextOptions {
  message: string;
  placeholder?: string;
  defaultValue?: string;
  initialValue?: string;
  validate?: (value: string) => string | Error | undefined;
}

interface PasswordOptions {
  message: string;
  mask?: string;
  validate?: (value: string) => string | Error | undefined;
}

interface ConfirmOptions {
  message: string;
  active?: string;
  inactive?: string;
  initialValue?: boolean;
}

type Option<Value> = Value extends Primitive
  ? {
      value: Value;
      label?: string;
      hint?: string;
    }
  : {
      value: Value;
      label: string;
      hint?: string;
    };

interface SelectOptions<Value> {
  message: string;
  options: Option<Value>[];
  initialValue?: Value;
  maxItems?: number;
}

interface MultiSelectOptions<Value> {
  message: string;
  options: Option<Value>[];
  initialValues?: Value[];
  maxItems?: number;
  required?: boolean;
  cursorAt?: Value;
}

interface GroupMultiSelectOptions<Value> {
  message: string;
  options: Record<string, Option<Value>[]>;
  initialValues?: Value[];
  required?: boolean;
  cursorAt?: Value;
  selectableGroups?: boolean;
}

interface SpinnerOptions {
  indicator?: 'dots' | 'timer';
}

interface LogMessageOptions {
  symbol?: string;
}

type Task = {
  title: string;
  task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>;
  enabled?: boolean;
};

type PromptGroup<T> = {
  [P in keyof T]: (opts: {
    results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>>;
  }) => undefined | Promise<T[P] | undefined>;
};

interface PromptGroupOptions<T> {
  onCancel?: (opts: { results: Prettify<Partial<PromptGroupAwaitedReturn<T>>> }) => void;
}

type PromptGroupAwaitedReturn<T> = {
  [P in keyof T]: Exclude<Awaited<T[P]>, symbol>;
};

type Prettify<T> = {
  [P in keyof T]: T[P];
} & {};

type Primitive = Readonly<string | boolean | number>;

interface ClackSettings {
  aliases: Record<string, Action>;
}

type Action = 'up' | 'down' | 'left' | 'right' | 'space' | 'enter' | 'cancel';