Prompts
The @clack/prompts package provides a collection of pre-built, high-level prompts that make it easy to create interactive command-line interfaces. It builds on top of the core package to provide a more developer-friendly experience.
Key Features
Section titled “Key Features”- Pre-built prompts: Ready-to-use prompt components
- Consistent styling: Unified look and feel across all prompts
- Type-safe: Full TypeScript support
- Customizable: Easy to extend and modify
- AbortController support: Cancel prompts programmatically
- Custom I/O streams: Use custom input/output streams
Installation
Section titled “Installation”npm install @clack/promptspnpm add @clack/promptsyarn add @clack/promptsThe prompts package is designed to be intuitive and easy to use. Each prompt function returns a Promise that resolves to the user’s input.
For more detailed examples and advanced usage patterns, check out our examples guide and best practices.
Common Options
Section titled “Common Options”All prompts share these common options:
Guide Lines
Section titled “Guide Lines”The withGuide option controls whether the default Clack border/guide lines are displayed. You can disable them globally or per-prompt:
import { const text: (opts: TextOptions) => Promise<string | symbol>
text, function updateSettings(updates: ClackSettings): void
updateSettings } from '@clack/prompts';
// Disable globallyfunction updateSettings(updates: ClackSettings): void
updateSettings({ ClackSettings.withGuide?: boolean
withGuide: false });
// Or per-promptconst const name: string | symbol
name = await function text(opts: TextOptions): Promise<string | symbol>
text({ TextOptions.message: string
message: 'What is your name?', CommonOptions.withGuide?: boolean
withGuide: false, // Disable guide lines for this prompt});AbortController Support
Section titled “AbortController Support”All prompts accept a signal option for programmatic cancellation:
import { const confirm: (opts: ConfirmOptions) => Promise<boolean | symbol>
confirm } from '@clack/prompts';
// Auto-cancel after 10 secondsconst const shouldContinue: boolean | symbol
shouldContinue = await function confirm(opts: ConfirmOptions): Promise<boolean | symbol>
confirm({ ConfirmOptions.message: string
message: 'This will self-destruct in 10 seconds', CommonOptions.signal?: AbortSignal
signal: var AbortSignal: { new (): AbortSignal; prototype: AbortSignal; abort(reason?: any): AbortSignal; any(signals: AbortSignal[]): AbortSignal; timeout(milliseconds: number): AbortSignal;}
AbortSignal.function timeout(milliseconds: number): AbortSignal
timeout(10000),});Custom I/O Streams
Section titled “Custom I/O Streams”You can provide custom input and output streams for all prompts:
import { class Writable
Writable, class Readable
Readable } from 'node:stream';import { const text: (opts: TextOptions) => Promise<string | symbol>
text } from '@clack/prompts';
declare const const customInput: Readable
customInput: class Readable
Readable;declare const const customOutput: Writable
customOutput: class Writable
Writable;
const const name: string | symbol
name = await function text(opts: TextOptions): Promise<string | symbol>
text({ TextOptions.message: string
message: 'What is your name?', CommonOptions.input?: Readable
input: const customInput: Readable
customInput, CommonOptions.output?: Writable
output: const customOutput: Writable
customOutput,});Available Prompts
Section titled “Available Prompts”Text Input
Section titled “Text Input”import { const text: (opts: TextOptions) => Promise<string | symbol>
text } from '@clack/prompts';
const const name: string | symbol
name = await function text(opts: TextOptions): Promise<string | symbol>
text({ TextOptions.message: string
message: 'What is your name?', TextOptions.placeholder?: string
placeholder: 'John Doe', TextOptions.validate?: (value: string | undefined) => string | Error | undefined
validate: (value: string | undefined
value) => { if (!value: string | undefined
value || value: string
value.String.length: number
Returns the length of a String object.
length < 2) return 'Name must be at least 2 characters'; return var undefined
undefined; },});│
◆ What is your name?
│ John Doe
└
Password Input
Section titled “Password Input”import { const password: (opts: PasswordOptions) => Promise<string | symbol>
password } from '@clack/prompts';
const const secret: string | symbol
secret = await function password(opts: PasswordOptions): Promise<string | symbol>
password({ PasswordOptions.message: string
message: 'What is your password?', PasswordOptions.mask?: string
mask: '*', PasswordOptions.clearOnError?: boolean
clearOnError: true, // Clear input when validation fails PasswordOptions.validate?: (value: string | undefined) => string | Error | undefined
validate: (value: string | undefined
value) => { if (!value: string | undefined
value || value: string
value.String.length: number
Returns the length of a String object.
length < 8) return 'Your password must be at least 8 characters'; if (!/[A-Z]/.RegExp.test(string: string): boolean
Returns a Boolean value that indicates whether or not a pattern exists in a searched string.
test(value: string
value)) return 'Your password must be least contain 1 uppercase letter'; if (!/[0-9]/.RegExp.test(string: string): boolean
Returns a Boolean value that indicates whether or not a pattern exists in a searched string.
test(value: string
value)) return 'Your password must be least contain 1 number'; if (!/[*?!@&]/.RegExp.test(string: string): boolean
Returns a Boolean value that indicates whether or not a pattern exists in a searched string.
test(value: string
value)) return 'Your password must be least contain 1 special characters (*?!@&)'; return var undefined
undefined; },});│
◆ What is your password?
│ *****_
└
Options:
message: The prompt message to displaymask: Character used to mask input (default:'▪')clearOnError: Whentrue, clears the input field when validation fails (useful for security)
Selection
Section titled “Selection”Simple value
Section titled “Simple value”import { const select: <Value>(opts: SelectOptions<Value>) => Promise<Value | symbol>
select } from '@clack/prompts';
const const framework: symbol | "next" | "astro" | "svelte"
framework = await select<"next" | "astro" | "svelte">(opts: SelectOptions<"next" | "astro" | "svelte">): Promise<symbol | "next" | "astro" | "svelte">
select({ SelectOptions<Value>.message: string
message: 'Pick a framework', SelectOptions<"next" | "astro" | "svelte">.options: ({ value: "next"; label?: string; hint?: string; disabled?: boolean;} | { value: "astro"; label?: string; hint?: string; disabled?: boolean;} | { value: "svelte"; label?: string; hint?: string; disabled?: boolean;})[]
options: [ { value: "next"
Internal data for this option.
value: 'next', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Next.js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'React framework' }, { value: "astro"
Internal data for this option.
value: 'astro', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Astro', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Content-focused' }, { value: "svelte"
Internal data for this option.
value: 'svelte', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'SvelteKit', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Compile-time framework' }, ], SelectOptions<Value>.maxItems?: number
maxItems: 5, // Maximum number of items to display at once});│ ◆ Pick a framework │ ● Next.js (React framework) │ ○ Astro (Content-focused) │ ○ SvelteKit (Compile-time framework) └
Complex value
Section titled “Complex value”import { const select: <Value>(opts: SelectOptions<Value>) => Promise<Value | symbol>
select } from '@clack/prompts';
const const framework: symbol | { framework: string; language: string;} | { framework: null; language: string;}
framework = await select<{ framework: string; language: string;} | { framework: null; language: string;}>(opts: SelectOptions<{ framework: string; language: string;} | { framework: null; language: string;}>): Promise<...>
select({ SelectOptions<Value>.message: string
message: 'Pick a framework', SelectOptions<{ framework: string; language: string; } | { framework: null; language: string; }>.options: ({ value: { framework: string; language: string; }; label: string; hint?: string; disabled?: boolean;} | { value: { framework: null; language: string; }; label: string; hint?: string; disabled?: boolean;})[]
options: [ { value: { framework: string; language: string;}
value: { framework: string
framework: 'Next', language: string
language: 'React' }, label: string
Required. The user-facing text for this option.
label: 'Next.js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'React framework' }, { value: { framework: null; language: string;}
value: { framework: null
framework: null, language: string
language: 'Astro' }, label: string
Required. The user-facing text for this option.
label: 'Astro', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Content-focused' }, { value: { framework: string; language: string;}
value: { framework: string
framework: 'Sveltekit', language: string
language: 'Svelte' }, label: string
Required. The user-facing text for this option.
label: 'SvelteKit', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Compile-time framework' }, ],});│ │ Pick a framework │ ● Next.js (React framework) │ ○ Astro (Content-focused) │ ○ SvelteKit (Compile-time framework) └
Disabled options
Section titled “Disabled options”You can disable specific options to prevent selection:
import { const select: <Value>(opts: SelectOptions<Value>) => Promise<Value | symbol>
select } from '@clack/prompts';
const const database: symbol | "postgres" | "mysql" | "mongodb" | "sqlite"
database = await select<"postgres" | "mysql" | "mongodb" | "sqlite">(opts: SelectOptions<"postgres" | "mysql" | "mongodb" | "sqlite">): Promise<symbol | "postgres" | "mysql" | "mongodb" | "sqlite">
select({ SelectOptions<Value>.message: string
message: 'Select a database', SelectOptions<"postgres" | "mysql" | "mongodb" | "sqlite">.options: ({ value: "postgres"; label?: string; hint?: string; disabled?: boolean;} | { value: "mysql"; label?: string; hint?: string; disabled?: boolean;} | { value: "mongodb"; label?: string; hint?: string; disabled?: boolean;} | { ...;})[]
options: [ { value: "postgres"
Internal data for this option.
value: 'postgres', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'PostgreSQL', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Recommended' }, { value: "mysql"
Internal data for this option.
value: 'mysql', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'MySQL' }, { value: "mongodb"
Internal data for this option.
value: 'mongodb', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'MongoDB', disabled?: boolean
Whether this option is disabled.
Disabled options are visible but cannot be selected.
By default, options are not disabled.
disabled: true, hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Coming soon' }, { value: "sqlite"
Internal data for this option.
value: 'sqlite', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'SQLite' }, ],});│ ◆ Select a database │ ● PostgreSQL (Recommended) │ ○ MySQL │ ○MongoDB(Coming soon) │ ○ SQLite └
Disabled options are displayed with strikethrough styling and cannot be selected.
Multiple values
Section titled “Multiple values”import { const multiselect: <Value>(opts: MultiSelectOptions<Value>) => Promise<Value[] | symbol>
multiselect } from '@clack/prompts';
const const framework: symbol | ({ framework: string; language: string;} | { framework: null; language: string;})[]
framework = await multiselect<{ framework: string; language: string;} | { framework: null; language: string;}>(opts: MultiSelectOptions<{ framework: string; language: string;} | { framework: null; language: string;}>): Promise<...>
multiselect({ MultiSelectOptions<Value>.message: string
message: 'Pick a framework', MultiSelectOptions<{ framework: string; language: string; } | { framework: null; language: string; }>.options: ({ value: { framework: string; language: string; }; label: string; hint?: string; disabled?: boolean;} | { value: { framework: null; language: string; }; label: string; hint?: string; disabled?: boolean;})[]
options: [ { value: { framework: string; language: string;}
value: { framework: string
framework: 'Next', language: string
language: 'React' }, label: string
Required. The user-facing text for this option.
label: 'Next.js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'React framework' }, { value: { framework: null; language: string;}
value: { framework: null
framework: null, language: string
language: 'Astro' }, label: string
Required. The user-facing text for this option.
label: 'Astro', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Content-focused' }, { value: { framework: string; language: string;}
value: { framework: string
framework: 'Sveltekit', language: string
language: 'Svelte' }, label: string
Required. The user-facing text for this option.
label: 'SvelteKit', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Compile-time framework' }, ], MultiSelectOptions<Value>.maxItems?: number
maxItems: 5, // Maximum number of items to display at once});│ ◆ Pick a framework │ ◼ Next.js (React framework) │ ◻ Astro (Content-focused) │ ◻ SvelteKit (Compile-time framework) └
Autocomplete
Section titled “Autocomplete”The autocomplete prompt combines text input with a searchable list of options. It’s perfect for when you have a large list of options and want to help users find what they’re looking for quickly.
import { const autocomplete: <Value>(opts: AutocompleteOptions<Value>) => Promise<Value | symbol>
autocomplete } from '@clack/prompts';
const const framework: symbol | "next" | "astro" | "svelte" | "remix" | "nuxt"
framework = await autocomplete<"next" | "astro" | "svelte" | "remix" | "nuxt">(opts: AutocompleteOptions<"next" | "astro" | "svelte" | "remix" | "nuxt">): Promise<symbol | "next" | "astro" | "svelte" | "remix" | "nuxt">
autocomplete({ AutocompleteSharedOptions<Value>.message: string
The message to display to the user.
message: 'Search for a framework', AutocompleteSharedOptions<"next" | "astro" | "svelte" | "remix" | "nuxt">.options: ({ value: "next"; label?: string; hint?: string; disabled?: boolean;} | { value: "astro"; label?: string; hint?: string; disabled?: boolean;} | { value: "svelte"; label?: string; hint?: string; disabled?: boolean;} | { ...;} | { ...;})[] | ((this: AutocompletePrompt<...>) => ({ value: "next"; label?: string; hint?: string; disabled?: boolean;} | ... 3 more ... | { ...;})[])
Available options for the autocomplete prompt.
options: [ { value: "next"
Internal data for this option.
value: 'next', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Next.js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'React framework' }, { value: "astro"
Internal data for this option.
value: 'astro', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Astro', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Content-focused' }, { value: "svelte"
Internal data for this option.
value: 'svelte', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'SvelteKit', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Compile-time framework' }, { value: "remix"
Internal data for this option.
value: 'remix', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Remix', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Full stack framework' }, { value: "nuxt"
Internal data for this option.
value: 'nuxt', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Nuxt', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Vue framework' }, ], AutocompleteSharedOptions<Value>.placeholder?: string
Placeholder text to display when no input is provided.
placeholder: 'Type to search...', AutocompleteSharedOptions<Value>.maxItems?: number
Maximum number of items to display at once.
maxItems: 5, // Maximum number of items to display at once});│
◆ Search for a framework
│ Search: n
│ (2 matches)
│ ● Next.js (React framework)
│ ○ Nuxt (Vue framework)
└
Autocomplete Multiselect
Section titled “Autocomplete Multiselect”The autocompleteMultiselect combines the search functionality of autocomplete with the ability to select multiple options.
import { const autocompleteMultiselect: <Value>(opts: AutocompleteMultiSelectOptions<Value>) => Promise<Value[] | symbol>
Integrated autocomplete multiselect - combines type-ahead filtering with multiselect in one UI
autocompleteMultiselect } from '@clack/prompts';
const const frameworks: symbol | ("next" | "astro" | "svelte" | "remix" | "nuxt")[]
frameworks = await autocompleteMultiselect<"next" | "astro" | "svelte" | "remix" | "nuxt">(opts: AutocompleteMultiSelectOptions<"next" | "astro" | "svelte" | "remix" | "nuxt">): Promise<...>
Integrated autocomplete multiselect - combines type-ahead filtering with multiselect in one UI
autocompleteMultiselect({ AutocompleteSharedOptions<Value>.message: string
The message to display to the user.
message: 'Select frameworks', AutocompleteSharedOptions<"next" | "astro" | "svelte" | "remix" | "nuxt">.options: ({ value: "next"; label?: string; hint?: string; disabled?: boolean;} | { value: "astro"; label?: string; hint?: string; disabled?: boolean;} | { value: "svelte"; label?: string; hint?: string; disabled?: boolean;} | { ...;} | { ...;})[] | ((this: AutocompletePrompt<...>) => ({ value: "next"; label?: string; hint?: string; disabled?: boolean;} | ... 3 more ... | { ...;})[])
Available options for the autocomplete prompt.
options: [ { value: "next"
Internal data for this option.
value: 'next', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Next.js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'React framework' }, { value: "astro"
Internal data for this option.
value: 'astro', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Astro', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Content-focused' }, { value: "svelte"
Internal data for this option.
value: 'svelte', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'SvelteKit', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Compile-time framework' }, { value: "remix"
Internal data for this option.
value: 'remix', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Remix', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Full stack framework' }, { value: "nuxt"
Internal data for this option.
value: 'nuxt', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Nuxt', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Vue framework' }, ], AutocompleteSharedOptions<Value>.placeholder?: string
Placeholder text to display when no input is provided.
placeholder: 'Type to search...', AutocompleteSharedOptions<Value>.maxItems?: number
Maximum number of items to display at once.
maxItems: 5, // Maximum number of items to display at once});│
◆ Select frameworks
│ Search: n
│ (2 matches)
│ ◼ Next.js (React framework)
│ ◻ Nuxt (Vue framework)
└
Path Selection
Section titled “Path Selection”The path prompt provides an autocomplete-based file and directory path selection. It automatically suggests files and directories as the user types.
import { const path: (opts: PathOptions) => Promise<string | symbol>
path } from '@clack/prompts';
const const selectedPath: string | symbol
selectedPath = await function path(opts: PathOptions): Promise<string | symbol>
path({ PathOptions.message: string
message: 'Select a file:', PathOptions.root?: string
root: var process: NodeJS.Process
process.NodeJS.Process.cwd(): string
The process.cwd() method returns the current working directory of the Node.js
process.
import { cwd } from 'node:process';
console.log(`Current directory: ${cwd()}`);
cwd(), // Starting directory PathOptions.directory?: boolean
directory: false, // Set to true to only show directories});│
◆ Select a file:
│ Search: /Users/project/
│ (3 matches)
│ ● /Users/project/src
│ ○ /Users/project/package.json
│ ○ /Users/project/tsconfig.json
└
Options:
message: The prompt message to displayroot: The starting directory for path suggestions (defaults to current working directory)directory: Whentrue, only directories are shown (defaults tofalse)initialValue: Pre-fill the path input with an initial valuevalidate: Custom validation function for the selected path
Confirmation
Section titled “Confirmation”import { const confirm: (opts: ConfirmOptions) => Promise<boolean | symbol>
confirm } from '@clack/prompts';
const const shouldProceed: boolean | symbol
shouldProceed = await function confirm(opts: ConfirmOptions): Promise<boolean | symbol>
confirm({ ConfirmOptions.message: string
message: 'Do you want to continue?',});│ ◆ Do you want to continue? │ ● Yes / ○ No └
Grouping
Section titled “Grouping”Group Multiselect
Section titled “Group Multiselect”import { const groupMultiselect: <Value>(opts: GroupMultiSelectOptions<Value>) => Promise<Value[] | symbol>
groupMultiselect } from '@clack/prompts';
const const projectOptions: symbol | ("Jest" | "Playwright" | "Vitest" | "js" | "ts" | "coffee" | "Prettier" | "ESLint" | "Biome.js")[]
projectOptions = await groupMultiselect<"Jest" | "Playwright" | "Vitest" | "js" | "ts" | "coffee" | "Prettier" | "ESLint" | "Biome.js">(opts: GroupMultiSelectOptions<"Jest" | "Playwright" | "Vitest" | "js" | "ts" | "coffee" | "Prettier" | "ESLint" | "Biome.js">): Promise<...>
groupMultiselect({ GroupMultiSelectOptions<Value>.message: string
message: 'Define your project', GroupMultiSelectOptions<"Jest" | "Playwright" | "Vitest" | "js" | "ts" | "coffee" | "Prettier" | "ESLint" | "Biome.js">.options: Record<string, ({ value: "Jest"; label?: string; hint?: string; disabled?: boolean;} | { value: "Playwright"; label?: string; hint?: string; disabled?: boolean;} | { value: "Vitest"; label?: string; hint?: string; disabled?: boolean;} | ... 5 more ... | { ...;})[]>
options: { 'Testing': [ { value: "Jest"
Internal data for this option.
value: 'Jest', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'JavaScript testing framework' }, { value: "Playwright"
Internal data for this option.
value: 'Playwright', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'End-to-end testing' }, { value: "Vitest"
Internal data for this option.
value: 'Vitest', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Vite-native testing' }, ], 'Language': [{ label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: "Javascript", value: "js"
Internal data for this option.
value: 'js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Dynamic typing' }, { label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'TypeScript', value: "ts"
Internal data for this option.
value: 'ts', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Static typing' }, { label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: "CoffeeScript", value: "coffee"
Internal data for this option.
value: 'coffee', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'JavaScript with Ruby-like syntax' }], 'Code quality': [ { value: "Prettier"
Internal data for this option.
value: 'Prettier', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Code formatter' }, { value: "ESLint"
Internal data for this option.
value: 'ESLint', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Linter' }, { value: "Biome.js"
Internal data for this option.
value: 'Biome.js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Formatter and linter' }, ], }, GroupMultiSelectOptions<Value>.groupSpacing?: number
groupSpacing: 1, // Add one new line between each group GroupMultiSelectOptions<Value>.selectableGroups?: boolean
selectableGroups: false, // Disable selection of top-level groups});│ ◆ Define your project │ ◼ Testing │ │ ◼ Jest (JavaScript testing framework) │ │ ◼ Playwright (End-to-end testing) │ └ ◼ Vitest (Vite-native testing) │ │ ◻ Language │ │ ◼ Javascript (Dynamic typing) │ │ ◻ TypeScript (Static typing) │ └ ◻ CoffeeScript (JavaScript with Ruby-like syntax) │ │ ◻ Code quality │ │ ◻ Prettier (Code formatter) │ │ ◻ ESLint (Linter) │ └ ◼ Biome.js (Formatter and linter) └
The groupMultiselect prompt supports two additional options:
groupSpacing: An integer that specifies how many new lines to add between each group. This helps improve readability when you have many groups.selectableGroups: A boolean that determines whether top-level groups can be selected. When set tofalse, only individual items within groups can be selected.
The group function provides a convenient API for combining a series of questions.
Each question receives the results of previous answers.
The group function returns an object containing the result of every question.
import { const group: <T>(prompts: PromptGroup<T>, opts?: PromptGroupOptions<T>) => Promise<{ [P in keyof PromptGroupAwaitedReturn<...>]: PromptGroupAwaitedReturn<...>[P]; }>
Define a group of prompts to be displayed
and return a results of objects within the group
group, const text: (opts: TextOptions) => Promise<string | symbol>
text, const password: (opts: PasswordOptions) => Promise<string | symbol>
password } from '@clack/prompts';
const const account: { email: string; username: unknown; password: string;}
account = await group<{ email: string | symbol; username: unknown; password: string | symbol;}>(prompts: PromptGroup<{ email: string | symbol; username: unknown; password: string | symbol;}>, opts?: PromptGroupOptions<{ email: string | symbol; username: unknown; password: string | symbol;}> | undefined): Promise<...>
Define a group of prompts to be displayed
and return a results of objects within the group
group({ email: (opts: { results: { username?: unknown; password?: string; };}) => Promise<string | symbol | undefined> | undefined
email: () => function text(opts: TextOptions): Promise<string | symbol>
text({ TextOptions.message: string
message: 'What is your email address?', TextOptions.validate?: (value: string | undefined) => string | Error | undefined
validate: (value: string | undefined
value) => { if (!value: string | undefined
value || !/^[a-z0-9_.-]+@[a-z0-9_.-]+\.[a-z]{2,}$/i.RegExp.test(string: string): boolean
Returns a Boolean value that indicates whether or not a pattern exists in a searched string.
test(value: string
value)) return 'Please enter a valid email' } }), username: (opts: { results: { email?: string; password?: string; };}) => Promise<unknown> | undefined
username: ({results: { email?: string; password?: string;}
results}) => function text(opts: TextOptions): Promise<string | symbol>
text({ TextOptions.message: string
message: 'What is your username?', TextOptions.placeholder?: string
placeholder: results: { email?: string; password?: string;}
results.email?: string | undefined
email?.String.replace(searchValue: string | RegExp, replaceValue: string): string (+3 overloads)
Replaces text in a string, using a regular expression or search string.
replace(/@.+$/, '').String.toLowerCase(): string
Converts all the alphabetic characters in a string to lowercase.
toLowerCase() ?? '', TextOptions.validate?: (value: string | undefined) => string | Error | undefined
validate: (value: string | undefined
value) => { // FOR DEMO PURPOSES ONLY! Use a robust validation library in production if (!value: string | undefined
value || value: string
value.String.length: number
Returns the length of a String object.
length < 2) return 'Please enter at least 2 characters' } }), password: (opts: { results: { email?: string; username?: unknown; };}) => Promise<string | symbol | undefined> | undefined
password: () => function password(opts: PasswordOptions): Promise<string | symbol>
password({ PasswordOptions.message: string
message: 'Define your password' }),});│ ◇ What is your email address? │ user.name@example.com │ ◇ What is your username? │ bomb_sh │ ◆ Define your password │ ▪▪▪▪▪▪▪▪▪▪▪▪_ └
The tasks function provides a convenient API for sequencing several asynchronous actions one after the other.
import { const tasks: (tasks: Task[], opts?: CommonOptions) => Promise<void>
Define a group of tasks to be executed
tasks } from "@clack/prompts";
await function tasks(tasks: Task[], opts?: CommonOptions): Promise<void>
Define a group of tasks to be executed
tasks([ { title: string
Task title
title: 'Downloading package', task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>
Task function
task: async () => { // Do a fetch return 'Download completed'; }, }, { title: string
Task title
title: "Un-archiving", task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>
Task function
task: async (message: (string: string) => void
message) => { const const parts: string[]
parts: interface Array<T>
Array<string> = [/* ... */]; for (let let index: number
index = 0; let index: number
index < const parts: string[]
parts.Array<T>.length: number
Gets or sets the length of the array. This is a number one higher than the highest index in the array.
length; let index: number
index++) { const const type: string
type = const parts: string[]
parts[let index: number
index]; // Update the message to indicate what is done message: (string: string) => void
message(`Un-archiving ${const type: string
type} (${let index: number
index + 1}/${const parts: string[]
parts.Array<T>.length: number
Gets or sets the length of the array. This is a number one higher than the highest index in the array.
length})`); // Do the un-archiving task } return 'Un-archiving completed'; }, }, { title: string
Task title
title: 'Linking', task: (message: (string: string) => void) => string | Promise<string> | void | Promise<void>
Task function
task: async () => { // Do work return 'Package linked'; }, },]);│ ◇ Download completed │ ◐ Un-archiving lib (2/3)..
Support functions
Section titled “Support functions”The intro function defines the beginning of an interaction.
It accepts an optional string parameter which is displayed as a title for the interaction.
import { const intro: (title?: string, opts?: CommonOptions) => void
intro } from '@clack/prompts';
function intro(title?: string, opts?: CommonOptions): void
intro('Welcome to clack');┌ Welcome to clack
The outro function defines the end of an interaction.
It accepts an optional string parameter which is displayed as a concluding message.
import { const outro: (message?: string, opts?: CommonOptions) => void
outro } from '@clack/prompts';
function outro(message?: string, opts?: CommonOptions): void
outro('All operations are finished');│ └ All operations are finished
Cancel
Section titled “Cancel”The cancel function defines an interruption of an interaction and therefore its end.
It accepts an optional string parameter which is displayed as a cancellation message.
import { const cancel: (message?: string, opts?: CommonOptions) => void
cancel } from '@clack/prompts';
function cancel(message?: string, opts?: CommonOptions): void
cancel('Installation canceled');└ Installation canceled
Spinner
Section titled “Spinner”The spinner function provides a loading indicator for long-running operations.
import { const spinner: ({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions) => SpinnerResult
spinner } from '@clack/prompts';
const const spin: SpinnerResult
spin = function spinner({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions): SpinnerResult
spinner();const spin: SpinnerResult
spin.SpinnerResult.start(msg?: string): void
start('Loading');// Do somethingconst spin: SpinnerResult
spin.SpinnerResult.message(msg?: string): void
message('Finishing');// Do more thingsconst spin: SpinnerResult
spin.SpinnerResult.stop(msg?: string): void
stop('Done');│ ◒ Loading...
Spinner Methods
Section titled “Spinner Methods”The spinner provides multiple methods to indicate different completion states:
import { const spinner: ({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions) => SpinnerResult
spinner } from '@clack/prompts';
const const spin: SpinnerResult
spin = function spinner({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions): SpinnerResult
spinner();const spin: SpinnerResult
spin.SpinnerResult.start(msg?: string): void
start('Processing');
// Success - shows green checkmarkconst spin: SpinnerResult
spin.SpinnerResult.stop(msg?: string): void
stop('Completed successfully');
// Or cancel - shows red square// spin.cancel('Operation cancelled');
// Or error - shows yellow triangle// spin.error('An error occurred');
// Or clear - stops without showing any message// spin.clear();You can also check if the spinner was cancelled via SIGINT (Ctrl+C):
import { const spinner: ({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions) => SpinnerResult
spinner } from '@clack/prompts';
const const spin: SpinnerResult
spin = function spinner({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions): SpinnerResult
spinner({ SpinnerOptions.onCancel?: () => void
onCancel: () => { var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
- A
Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
- A global
console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');// Prints: hello world, to stdoutconsole.log('hello %s', 'world');// Prints: hello world, to stdoutconsole.error(new Error('Whoops, something bad happened'));// Prints error message and stack trace to stderr:// Error: Whoops, something bad happened// at [eval]:5:15// at Script.runInThisContext (node:vm:132:18)// at Object.runInThisContext (node:vm:309:38)// at node:internal/process/execution:77:19// at [eval]-wrapper:6:22// at evalScript (node:internal/process/execution:76:60)// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';console.warn(`Danger ${name}! Danger!`);// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();const err = getStreamSomehow();const myConsole = new console.Console(out, err);
myConsole.log('hello world');// Prints: hello world, to outmyConsole.log('hello %s', 'world');// Prints: hello world, to outmyConsole.error(new Error('Whoops, something bad happened'));// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';myConsole.warn(`Danger ${name}! Danger!`);// Prints: Danger Will Robinson! Danger!, to err
console.Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;console.log('count: %d', count);// Prints: count: 5, to stdoutconsole.log('count:', count);// Prints: count: 5, to stdout
See util.format() for more information.
log('User pressed Ctrl+C'); }});
const spin: SpinnerResult
spin.SpinnerResult.start(msg?: string): void
start('Long running task');// ... after some workif (const spin: SpinnerResult
spin.SpinnerResult.isCancelled: boolean
isCancelled) { // Handle cancellation}Customization Options
Section titled “Customization Options”import { const spinner: ({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions) => SpinnerResult
spinner, function updateSettings(updates: ClackSettings): void
updateSettings } from '@clack/prompts';
// Global customization for i18nfunction updateSettings(updates: ClackSettings): void
updateSettings({ ClackSettings.messages?: { cancel?: string; error?: string;}
Custom messages for prompts
messages: { cancel?: string
Custom message to display when a spinner is cancelled
cancel: "Operation cancelled", error?: string
Custom message to display when a spinner encounters an error
error: "An error occurred", },});
// Per-instance customizationconst const spin: SpinnerResult
spin = function spinner({ indicator, onCancel, output, cancelMessage, errorMessage, frames, delay, signal, ...opts }?: SpinnerOptions): SpinnerResult
spinner({ SpinnerOptions.indicator?: "dots" | "timer"
indicator: 'timer', // 'dots' (default) or 'timer' for elapsed time display SpinnerOptions.cancelMessage?: string
cancelMessage: "Process cancelled", SpinnerOptions.errorMessage?: string
errorMessage: "Process failed", SpinnerOptions.frames?: string[]
frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'], // Custom animation frames SpinnerOptions.delay?: number
delay: 80, // Animation delay in ms SpinnerOptions.styleFrame?: (frame: string) => string
styleFrame: (frame: string
frame) => `\x1b[35m${frame: string
frame}\x1b[0m`, // Custom frame styling});
const spin: SpinnerResult
spin.SpinnerResult.start(msg?: string): void
start('Loading');// Do somethingconst spin: SpinnerResult
spin.SpinnerResult.stop(msg?: string): void
stop('Done');The indicator option supports two modes:
'dots': Animated dots that cycle (default)'timer': Shows elapsed time like[5s]or[1m 30s]
Progress
Section titled “Progress”The progress function displays a progress bar for long-running operations with multiple visual styles.
import { function progress({ style, max: userMax, size: userSize, ...spinnerOptions }?: ProgressOptions): ProgressResult
progress } from '@clack/prompts';
const const prog: ProgressResult
prog = function progress({ style, max: userMax, size: userSize, ...spinnerOptions }?: ProgressOptions): ProgressResult
progress({ ProgressOptions.style?: "light" | "heavy" | "block"
style: 'heavy', // 'light', 'heavy', or 'block' ProgressOptions.max?: number
max: 100, // Maximum value (default: 100) ProgressOptions.size?: number
size: 40, // Width of the progress bar (default: 40)});
const prog: ProgressResult
prog.SpinnerResult.start(msg?: string): void
start('Processing files');
// Advance the progress barconst prog: ProgressResult
prog.ProgressResult.advance(step?: number, msg?: string): void
advance(10); // Advance by 10 stepsconst prog: ProgressResult
prog.ProgressResult.advance(step?: number, msg?: string): void
advance(25, 'Processing images...'); // Advance with a message update
// Update just the messageconst prog: ProgressResult
prog.SpinnerResult.message(msg?: string): void
message('Almost done...');
// Complete the progressconst prog: ProgressResult
prog.SpinnerResult.stop(msg?: string): void
stop('All files processed');│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Processing images…
The progress bar supports three visual styles:
'light': Uses thin lines (─)'heavy': Uses thick lines (━) - default'block': Uses solid blocks (█)
Additional methods:
advance(step?, msg?): Advance the progress bar bystep(default: 1) and optionally update the messagemessage(msg): Update the displayed message without advancingstop(msg?): Complete the progress bar with a success messagecancel(msg?): Stop with a cancellation indicatorerror(msg?): Stop with an error indicatorclear(): Stop and clear the progress bar without a message
You can also use the timer indicator mode for time-based feedback:
import { function progress({ style, max: userMax, size: userSize, ...spinnerOptions }?: ProgressOptions): ProgressResult
progress } from '@clack/prompts';
const const prog: ProgressResult
prog = function progress({ style, max: userMax, size: userSize, ...spinnerOptions }?: ProgressOptions): ProgressResult
progress({ SpinnerOptions.indicator?: "dots" | "timer"
indicator: 'timer', // Shows elapsed time instead of animated dots ProgressOptions.style?: "light" | "heavy" | "block"
style: 'block', ProgressOptions.max?: number
max: 50,});
const prog: ProgressResult
prog.SpinnerResult.start(msg?: string): void
start('Downloading');// Progress shows: ████████████░░░░░░░░ Downloading [5s]The note function renders a box around a message to draw a user’s attention.
This is useful for displaying next steps and linking to your documentation towards the end of an interaction.
import { const note: (message?: string, title?: string, opts?: NoteOptions) => void
note } from '@clack/prompts';
function note(message?: string, title?: string, opts?: NoteOptions): void
note( 'You can edit the file src/index.jsx', 'Next steps.');│ ◇ Next steps. ─────────────────────────╮ │ │ │ You can edit the file src/index.jsx │ │ │ ├───────────────────────────────────────╯
The second parameter (the title) is optional. You can also provide a format function to customize how each line is displayed:
import { const note: (message?: string, title?: string, opts?: NoteOptions) => void
note } from '@clack/prompts';
function note(message?: string, title?: string, opts?: NoteOptions): void
note( 'Line 1\nLine 2\nLine 3', 'Formatted steps', { NoteOptions.format?: FormatFn
format: (line: string
line: string) => `→ ${line: string
line}` });│ ◇ Formatted steps ◇ ─────────────────────────────╮ │ │ │ → Line 1 │ │ → Line 2 │ │ → Line 3 │ │ │ ├────────────────────────────────╯
The box function renders a customizable box around text content. It’s similar to note but offers more styling options.
import { const box: (message?: string, title?: string, opts?: BoxOptions) => void
box } from '@clack/prompts';
function box(message?: string, title?: string, opts?: BoxOptions): void
box('This is the content of the box', 'Box Title', { BoxOptions.contentAlign?: BoxAlignment
contentAlign: 'center', BoxOptions.titleAlign?: BoxAlignment
titleAlign: 'center', BoxOptions.width?: number | "auto"
width: 'auto', BoxOptions.rounded?: boolean
rounded: true,});│ ╭──────────Box Title───────────╮ │ │ │ │ │ This is the content of the │ │ │ box │ │ │ │ │ ╰──────────────────────────────╯
Options:
contentAlign: Alignment of the content ('left','center', or'right')titleAlign: Alignment of the title ('left','center', or'right')width: Box width - use'auto'to fit content or a number for fixed widthtitlePadding: Padding around the titlecontentPadding: Padding around the contentrounded: Use rounded corners whentrue(default), square corners whenfalseformatBorder: Custom function to style the border characters
Task Log
Section titled “Task Log”The taskLog prompt provides a way to display log output that is cleared on success. This is useful for showing progress or status updates that should be removed once the task is complete.
import { const taskLog: (opts: TaskLogOptions) => { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
Renders a log which clears on success and remains on failure
taskLog } from '@clack/prompts';
const const log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log = function taskLog(opts: TaskLogOptions): { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
Renders a log which clears on success and remains on failure
taskLog({ TaskLogOptions.title: string
title: 'Installing dependencies', TaskLogOptions.limit?: number
limit: 10, // Limit visible log lines (optional) TaskLogOptions.retainLog?: boolean
retainLog: false, // Keep full log history (optional)});const log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log.function message(msg: string, mopts?: TaskLogMessageOptions): void
message('Fetching package information...');// Do some workconst log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log.function message(msg: string, mopts?: TaskLogMessageOptions): void
message('Installing packages...');// Do more workconst log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log.function success(message: string, opts?: TaskLogCompletionOptions): void
success('Installation complete');│ ◆ Installing dependencies │ Fetching package information… │ Installing packages… ◆ Installation complete
Task Log Groups
Section titled “Task Log Groups”Task logs support named groups, which allow you to organize logs into separate sections with their own headers and completion states:
import { const taskLog: (opts: TaskLogOptions) => { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
Renders a log which clears on success and remains on failure
taskLog } from '@clack/prompts';
const const log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log = function taskLog(opts: TaskLogOptions): { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
Renders a log which clears on success and remains on failure
taskLog({ TaskLogOptions.title: string
title: 'Building project'});
// Create a group for TypeScript compilationconst const tsGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
tsGroup = const log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log.function group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
group('Compiling TypeScript');const tsGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
tsGroup.function message(msg: string, mopts?: TaskLogMessageOptions): void
message('Processing src/index.ts...');const tsGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
tsGroup.function message(msg: string, mopts?: TaskLogMessageOptions): void
message('Processing src/utils.ts...');const tsGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
tsGroup.function success(message: string): void
success('TypeScript compiled');
// Create another group for bundlingconst const bundleGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
bundleGroup = const log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log.function group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
group('Bundling');const bundleGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
bundleGroup.function message(msg: string, mopts?: TaskLogMessageOptions): void
message('Creating bundle...');const bundleGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
bundleGroup.function message(msg: string, mopts?: TaskLogMessageOptions): void
message('Minifying...');const bundleGroup: { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void;}
bundleGroup.function success(message: string): void
success('Bundle created');
// Complete the overall taskconst log: { message(msg: string, mopts?: TaskLogMessageOptions): void; group(name: string): { message(msg: string, mopts?: TaskLogMessageOptions): void; error(message: string): void; success(message: string): void; }; error(message: string, opts?: TaskLogCompletionOptions): void; success(message: string, opts?: TaskLogCompletionOptions): void;}
log.function success(message: string, opts?: TaskLogCompletionOptions): void
success('Build complete');Each group has its own message(), success(), and error() methods, allowing independent tracking of subtasks within a larger operation.
The log utilities allow you to add semantic contextual information during an interaction.
Each function renders with specific styling to communicate status.
log is an object containing the following methods:
log.messagedisplays a message without any symbols to communicate statelog.infodisplays a message with a neutral statelog.warn(aliaslog.warning) displays a message with a caution statelog.errordisplays a message with a danger statelog.successdisplays a message with a success statelog.stepdisplays a message with a neutral, completed state
import { const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log } from '@clack/prompts';
const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log.message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void
message('Entering directory "src"');const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log.info: (message: string, opts?: LogMessageOptions) => void
info('No files to update');const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log.warn: (message: string, opts?: LogMessageOptions) => void
warn('Directory is empty, skipping');const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log.warning: (message: string, opts?: LogMessageOptions) => void
alias for log.warn().
warning('Directory is empty, skipping');const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log.error: (message: string, opts?: LogMessageOptions) => void
error('Permission denied on file src/secret.js');const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log.success: (message: string, opts?: LogMessageOptions) => void
success('Installation complete');const log: { message: (message?: string | string[], { symbol, secondarySymbol, output, spacing, withGuide, }?: LogMessageOptions) => void; info: (message: string, opts?: LogMessageOptions) => void; ... 4 more ...; error: (message: string, opts?: LogMessageOptions) => void;}
log.step: (message: string, opts?: LogMessageOptions) => void
step('Check files');│ │ Entering directory “src” │ ● No files to update │ ▲ Directory is empty, skipping │ ▲ Directory is empty, skipping │ ■ Permission denied on file src/secret.js │ ◆ Installation complete │ ◇ Check files
Internationalization
Section titled “Internationalization”The prompts package supports internationalization through the updateSettings function. You can customize the messages used by various prompts to match your preferred language.
import { function updateSettings(updates: ClackSettings): void
updateSettings, const select: <Value>(opts: SelectOptions<Value>) => Promise<Value | symbol>
select, const cancel: (message?: string, opts?: CommonOptions) => void
cancel } from '@clack/prompts';
// Update global messagesfunction updateSettings(updates: ClackSettings): void
updateSettings({ ClackSettings.messages?: { cancel?: string; error?: string;}
Custom messages for prompts
messages: { cancel?: string
Custom message to display when a spinner is cancelled
cancel: "Operación cancelada", error?: string
Custom message to display when a spinner encounters an error
error: "Se ha producido un error" }});
// Use the select prompt with translated contentconst const framework: symbol | "next" | "astro" | "svelte"
framework = await select<"next" | "astro" | "svelte">(opts: SelectOptions<"next" | "astro" | "svelte">): Promise<symbol | "next" | "astro" | "svelte">
select({ SelectOptions<Value>.message: string
message: 'Selecciona un framework', SelectOptions<"next" | "astro" | "svelte">.options: ({ value: "next"; label?: string; hint?: string; disabled?: boolean;} | { value: "astro"; label?: string; hint?: string; disabled?: boolean;} | { value: "svelte"; label?: string; hint?: string; disabled?: boolean;})[]
options: [ { value: "next"
Internal data for this option.
value: 'next', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Next.js', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Framework de React' }, { value: "astro"
Internal data for this option.
value: 'astro', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'Astro', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Enfocado en contenido' }, { value: "svelte"
Internal data for this option.
value: 'svelte', label?: string
The optional, user-facing text for this option.
By default, the value is converted to a string.
label: 'SvelteKit', hint?: string
An optional hint to display to the user when
this option might be selected.
By default, no hint is displayed.
hint: 'Framework de compilación' }, ]});
// If the user cancels, they'll see the translated messageif (!const framework: symbol | "next" | "astro" | "svelte"
framework) { function cancel(message?: string, opts?: CommonOptions): void
cancel();}│ ◆ Selecciona un framework │ ● Next.js (Framework de React) │ ○ Astro (Enfocado en contenido) │ ○ SvelteKit (Framework de compilación) └ └ Operación cancelada
Stream
Section titled “Stream”The stream utilities allow you, like the log utilities, to add semantic contextual information during an interaction,
except that the message contains an unknown number of lines.
Each function renders with specific styling to communicate status.
import { const stream: { message: (iterable: Iterable<string> | AsyncIterable<string>, { symbol }?: LogMessageOptions) => Promise<void>; info: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>; ... 4 more ...; error: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;}
stream } from "@clack/prompts";import * as module "node:fs"
fs from "node:fs";
await const stream: { message: (iterable: Iterable<string> | AsyncIterable<string>, { symbol }?: LogMessageOptions) => Promise<void>; info: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>; ... 4 more ...; error: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;}
stream.message: (iterable: Iterable<string> | AsyncIterable<string>, { symbol }?: LogMessageOptions) => Promise<void>
message(module "node:fs"
fs.function createReadStream(path: fs.PathLike, options?: BufferEncoding | ReadStreamOptions): fs.ReadStream
options can include start and end values to read a range of bytes from
the file instead of the entire file. Both start and end are inclusive and
start counting at 0, allowed values are in the
[0, Number.MAX_SAFE_INTEGER] range. If fd is specified and start is
omitted or undefined, fs.createReadStream() reads sequentially from the
current file position. The encoding can be any one of those accepted by Buffer.
If fd is specified, ReadStream will ignore the path argument and will use
the specified file descriptor. This means that no 'open' event will be
emitted. fd should be blocking; non-blocking fds should be passed to net.Socket.
If fd points to a character device that only supports blocking reads
(such as keyboard or sound card), read operations do not finish until data is
available. This can prevent the process from exiting and the stream from
closing naturally.
By default, the stream will emit a 'close' event after it has been
destroyed. Set the emitClose option to false to change this behavior.
By providing the fs option, it is possible to override the corresponding fs implementations for open, read, and close. When providing the fs option,
an override for read is required. If no fd is provided, an override for open is also required. If autoClose is true, an override for close is
also required.
import { createReadStream } from 'node:fs';
// Create a stream from some character device.const stream = createReadStream('/dev/input/event0');setTimeout(() => { stream.close(); // This may not close the stream. // Artificially marking end-of-stream, as if the underlying resource had // indicated end-of-file by itself, allows the stream to close. // This does not cancel pending read operations, and if there is such an // operation, the process may still not be able to exit successfully // until it finishes. stream.push(null); stream.read(0);}, 100);
If autoClose is false, then the file descriptor won't be closed, even if
there's an error. It is the application's responsibility to close it and make
sure there's no file descriptor leak. If autoClose is set to true (default
behavior), on 'error' or 'end' the file descriptor will be closed
automatically.
mode sets the file mode (permission and sticky bits), but only if the
file was created.
An example to read the last 10 bytes of a file which is 100 bytes long:
import { createReadStream } from 'node:fs';
createReadStream('sample.txt', { start: 90, end: 99 });
If options is a string, then it specifies the encoding.
createReadStream('./banner.txt', { StreamOptions.encoding?: BufferEncoding | undefined
encoding: 'utf-8' }));await const stream: { message: (iterable: Iterable<string> | AsyncIterable<string>, { symbol }?: LogMessageOptions) => Promise<void>; info: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>; ... 4 more ...; error: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;}
stream.info: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>
info((async function*() { yield 'Open file...'; // Open file yield ' \x1b[32mOK\x1b[39m\n';
yield 'Parsing file...'; // Parse data yield ' \x1b[32mOK\x1b[39m'; return;})());await const stream: { message: (iterable: Iterable<string> | AsyncIterable<string>, { symbol }?: LogMessageOptions) => Promise<void>; info: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>; ... 4 more ...; error: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>;}
stream.step: (iterable: Iterable<string> | AsyncIterable<string>) => Promise<void>
step([ 'Job1...', ' \x1b[32mdone\x1b[39m\n', 'Job2...', ' \x1b[32mdone\x1b[39m\n', 'Job3...', ' \x1b[32mdone\x1b[39m',]);│ │ │ ⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣶⣶⣿⣿⣿⣿⣿⣿⣶⣶⣤⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ │ ⠀⠀⠀⠀⠀⣠⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ │ ⠀⠀⠀⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ │ ⠀⠀⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ │ ⠀⣼⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀ │ ⢰⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⣀⠀⠀⠀⠀⣿⣿⣿⡿⠀⠀⠀⠀⣀⠀ │ ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⠀⠀⠀⠀⢠⣿⣿⣶⣤⣄⣻⣿⣿⣇⣠⣴⣶⣿⣿⡀ │ ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⢾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡧ │ ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠀⠀⠀⠀⠀⠀⠀⠉⢉⣿⣿⣿⣿⣿⣯⡉⠉⠀⠀⠀ │ ⠸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⢀⣴⣿⣿⣿⠟⢻⣿⣿⣿⣦⠀⠀⠀ │ ⠀⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡟⠀⠀⠀⠀⠀⠀⠐⠿⣿⣿⣿⠏⠀⠀⢻⣿⣿⣿⠷⠀⠀ │ ⠀⠀⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠏⠀⠀⠀⠀⠹⠋⠁⠀⠀⠀ │ ⠀⠀⠀⠙⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ │ ⠀⠀⠀⠀⠀⠙⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ │ ⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠻⠿⢿⣿⣿⣿⣿⡿⠿⠟⠛⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ │ │ ● Open file... OK │ Parsing file... OK │ ◇ Job1... done │ Job2... done │ Job3... done