cli-prompts-clack ยท diff
git:20260709.8364ee5 to git:20260809.a3281b1
28 added, 7 removed. Audit A to A.
---
name: cli-prompts-clack
description: Beautiful interactive CLI prompts with @clack/prompts and custom prompts with @clack/core
---
# Clack CLI Prompts
- > **Quick Guide:** Use `@clack/prompts` for pre-styled interactive CLI prompts (text, select, multiselect, confirm, spinner, progress). Check `isCancel()` after EVERY prompt call -- users can Ctrl+C at any point. Use `group()` for multi-step flows with centralized cancellation. Use `@clack/core` only when building fully custom prompt UIs. ESM-only since v1.0.
+ > **Quick Guide:** Use `@clack/prompts` for pre-styled interactive CLI prompts (text, select, multiselect, confirm, spinner, progress). Check `isCancel()` after EVERY prompt call -- users can Ctrl+C at any point. `cancel()` only prints; exit after it, with a non-zero code. Use `group()` for multi-step flows with centralized cancellation. Use `@clack/core` only when building fully custom prompt UIs. ESM-only since v1.0.
---
<critical_requirements>
## CRITICAL: Before Using This Skill
> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)
**(You MUST check `isCancel()` after EVERY prompt call -- skipping this causes silent crashes when users press Ctrl+C)**
- **(You MUST call `process.exit(0)` after `cancel()` -- the cancel message prints but the process keeps running otherwise)**
+ **(You MUST exit the process after `cancel()` -- the cancel message prints but execution continues otherwise)**
+ **(You MUST exit with a NON-ZERO code on cancellation, taking the value from the CLI framework's exit-code table where one exists and using 130 where none does -- exiting 0 tells every caller the work succeeded)**
+
**(You MUST use `group()` with `onCancel` for multi-step flows -- it handles cancellation centrally so you don't check each prompt individually)**
**(You MUST call `spinner.stop()` before any other output -- overlapping spinner output with prompts or logs corrupts the terminal)**
</critical_requirements>
---
**Auto-detection:** @clack/prompts, @clack/core, clack, isCancel, intro, outro, cancel, spinner, group, text prompt, select prompt, confirm prompt, multiselect, groupMultiselect, selectKey, note, log, tasks, progress, taskLog, stream, box, autocomplete, date prompt, path prompt, updateSettings
**When to use:**
- Building interactive CLI prompts (text input, selection, confirmation)
- Creating multi-step CLI wizards with progress indication
- Adding styled terminal output (notes, logs, boxes, spinners)
- Handling user cancellation gracefully across prompt flows
**When NOT to use:**
- Full terminal UI applications with persistent layout (use a terminal UI framework)
- Non-interactive scripts where stdin is piped (clack prompts require a TTY)
- Simple `y/n` confirmation that doesn't need styling (plain readline suffices)
**Key patterns covered:**
- Core prompts: text, password, select, multiselect, confirm, selectKey
- Session lifecycle: intro, outro, cancel, isCancel
- Progress: spinner, progress bar, tasks
- Composition: group with centralized cancellation
- Output: log, note, box, stream, taskLog
- Custom prompts with @clack/core primitives
- Validation, default values, and AbortSignal cancellation
---
<philosophy>
## Philosophy
Clack provides beautiful, minimal CLI prompts with zero configuration. The `@clack/prompts` package gives you pre-styled components that look great out of the box. Every prompt returns a value or a cancel symbol -- the core discipline is always checking for cancellation.
**Two packages, two purposes:**
- **`@clack/prompts`** -- Pre-styled, opinionated prompts. Use this for 95% of cases.
- **`@clack/core`** -- Unstyled primitives with a `render()` function. Use only when you need a completely custom prompt UI.
**Key design principles:**
- Every prompt is async and returns `value | symbol` -- the symbol indicates cancellation
- Session boundaries (`intro`/`outro`) create visual grouping in the terminal
- `group()` composes multiple prompts with shared cancellation handling
- Spinners, progress bars, and task runners handle long-running operations
- All prompts accept `signal: AbortSignal` for programmatic cancellation
</philosophy>
---
<patterns>
## Core Patterns
### Pattern 1: Session Lifecycle and Cancellation
Every clack CLI flow starts with `intro()` and ends with `outro()`. The critical pattern is checking `isCancel()` after every prompt call.
```typescript
import * as p from "@clack/prompts";
+ // 128 + SIGINT(2), the value a shell reports for an interrupted command.
+ // Use only when no CLI framework owns an exit-code table -- see below.
+ const EXIT_CANCELLED = 130;
+
p.intro("Project setup");
const name = await p.text({ message: "Project name?" });
if (p.isCancel(name)) {
p.cancel("Setup cancelled.");
- process.exit(0);
+ process.exit(EXIT_CANCELLED);
}
// name is now narrowed to string (not symbol)
p.outro(`Created ${name}`);
```
- **Why good:** isCancel check narrows the type from `string | symbol` to `string`, cancel prints a styled message, process.exit prevents dangling execution
+ **Why good:** isCancel check narrows the type from `string | symbol` to `string`, cancel prints a styled message, the exit stops dangling execution, the non-zero code stops callers from reading an abandoned run as a completed one
```typescript
// BAD: Missing isCancel check
const name = await p.text({ message: "Project name?" });
console.log(`Created ${name}`); // name could be a symbol -- crashes or prints "[Symbol]"
```
**Why bad:** if user presses Ctrl+C, name is a symbol, not a string -- string operations on it will crash or produce garbage output
+ #### Which code to exit with
+
+ `cancel()` prints and returns; it never stops the process. What you exit _with_ is a separate decision, and it is not this library's to make:
+
+ | Situation | Exit with |
+ | -------------------------------------------- | ------------------------------------------------------------------------- |
+ | The CLI framework defines an exit-code table | That table's cancellation constant. It is the authority; do not override. |
+ | A standalone script with no such table | `130` -- 128 + SIGINT(2), what a shell reports for an interrupted command |
+ | Never | `0` |
+
+ **Why never 0:** `0` means success, and `cli && deploy`, `set -e`, CI steps and every other caller act on exactly that. A user who pressed Ctrl+C halfway through setup did not succeed, so a `0` exit hands the next command a half-configured project and no signal that anything went wrong. Upstream examples showing `process.exit(0)` are illustrating _that you must exit at all_ -- the point they make is about the missing exit, not about the value.
+
---
### Pattern 2: Group Prompts with Centralized Cancellation
`group()` chains multiple prompts and handles cancellation in one place. Each prompt receives previous results.
```typescript
import * as p from "@clack/prompts";
const project = await p.group(
{
name: () => p.text({ message: "Project name?", placeholder: "my-app" }),
framework: ({ results }) =>
p.select({
message: `Framework for ${results.name}?`,
options: [
{ value: "react", label: "React" },
{ value: "vue", label: "Vue" },
{ value: "svelte", label: "Svelte" },
],
}),
install: () => p.confirm({ message: "Install dependencies?" }),
},
{
onCancel: () => {
p.cancel("Setup cancelled.");
- process.exit(0);
+ process.exit(EXIT_CANCELLED);
},
},
);
// project is typed: { name: string; framework: string; install: boolean }
```
- **Why good:** centralized onCancel eliminates per-prompt isCancel checks, results are typed as an object, each prompt can reference previous results via `results`
+ **Why good:** centralized onCancel eliminates per-prompt isCancel checks, results are typed as an object, each prompt can reference previous results via `results`, the single exit point means the cancellation code is decided once for the whole flow
See [examples/core.md](examples/core.md) for complete group patterns with validation and conditional prompts.
---
### Pattern 3: Spinner and Progress
Spinners show activity during async work. Always stop the spinner before printing other output.
```typescript
import * as p from "@clack/prompts";
const s = p.spinner();
s.start("Installing dependencies");
await installDeps();
s.stop("Dependencies installed");
```
**Progress bar** extends spinner with incremental tracking:
```typescript
const MAX_STEPS = 100;
const prog = p.progress({ max: MAX_STEPS, style: "heavy" });
prog.start("Processing files");
for (const file of files) {
await processFile(file);
prog.advance(1, `Processed ${file.name}`);
}
prog.stop("All files processed");
```
**Why good:** spinner and progress provide visual feedback, stop message replaces the spinner line cleanly
See [examples/core.md](examples/core.md) for spinner error handling, cancellation with AbortSignal, and tasks runner.
---
### Pattern 4: Validation
All input prompts accept a `validate` function. Return a string to show an error, or `undefined` to accept.
```typescript
const MIN_LENGTH = 2;
const MAX_LENGTH = 50;
const name = await p.text({
message: "Package name?",
validate: (value) => {
if (!value || value.length < MIN_LENGTH)
return `Name must be at least ${MIN_LENGTH} characters`;
if (value.length > MAX_LENGTH)
return `Name must be at most ${MAX_LENGTH} characters`;
if (!/^[a-z0-9-]+$/.test(value))
return "Name must be lowercase alphanumeric with hyphens";
},
});
```
**Why good:** validation runs inline before the prompt resolves, user sees the error immediately and can retry, named constants for limits
See [examples/core.md](examples/core.md) for validation patterns on different prompt types.
---
### Pattern 5: Output Utilities (log, note, box)
Clack provides styled output functions that match the prompt theme.
```typescript
import * as p from "@clack/prompts";
// Logging with state symbols
p.log.info("Checking configuration...");
p.log.success("Configuration valid");
p.log.warn("Missing optional field: description");
p.log.error("Invalid config file");
p.log.step("Step 1 complete");
// Boxed note for important information
p.note("Run `npm start` to begin development", "Next steps");
// Styled box
p.box("v1.0.0 released!", "Announcement", {
contentAlign: "center",
rounded: true,
});
```
**Why good:** themed output matches prompt styling, note/box draw attention to important information
---
### Pattern 6: Tasks Runner
Sequential tasks with automatic success/failure messaging.
```typescript
import * as p from "@clack/prompts";
await p.tasks([
{
title: "Downloading template",
task: async () => {
await downloadTemplate();
return "Template downloaded";
},
},
{
title: "Installing dependencies",
task: async (message) => {
message("Resolving packages...");
await installDeps();
return "Dependencies installed";
},
},
]);
```
**Why good:** tasks display spinner per item, return value becomes the completion message, `message()` callback updates spinner text mid-task
See [examples/core.md](examples/core.md) for error handling in tasks and taskLog for detailed output.
</patterns>
---
**Detailed Resources:**
- [examples/core.md](examples/core.md) - All prompt types, cancellation, spinner, progress, tasks, group, validation, output
- [examples/advanced.md](examples/advanced.md) - Custom prompts with @clack/core, AbortSignal, streams, i18n, date/path/autocomplete
- [reference.md](reference.md) - API quick reference, decision framework, prompt type comparison
---
<decision_framework>
## Decision Framework
```
Need user input?
|
+-> Single value?
| +-> Free text -> text() or password()
| +-> One of N choices -> select() (list) or selectKey() (keyboard shortcut)
| +-> Yes/No -> confirm()
| +-> Date -> date()
| +-> File path -> path()
|
+-> Multiple values?
| +-> Flat list -> multiselect()
| +-> Grouped categories -> groupMultiselect()
| +-> Searchable -> autocomplete() or autocompleteMultiselect()
|
+-> Multiple prompts in sequence?
+-> group() with onCancel for centralized handling
Need to show progress?
|
+-> Indeterminate wait -> spinner()
+-> Known total steps -> progress()
+-> Sequential tasks -> tasks()
+-> Detailed logs per task -> taskLog()
Need styled output?
|
+-> Status message -> log.info/warn/error/success/step()
+-> Important notice -> note() or box()
+-> Streaming content -> stream.info/warn/error/success()
```
</decision_framework>
---
<red_flags>
## RED FLAGS
**High Priority Issues:**
- **Missing `isCancel()` check after a prompt** -- the return value is `value | symbol`, and using the symbol as a string crashes or produces garbage. Always check before using the value.
- **Missing `process.exit()` after `cancel()`** -- `cancel()` only prints a message, it does not stop execution. The process continues running.
+ - **Exiting `0` after `cancel()`** -- a cancelled run reports success to every caller, so `cli && next-step` runs the next step against a half-finished state. Exit non-zero: the framework's cancellation constant, or `130` when there is no framework table.
- **Calling another prompt while spinner is active** -- spinner output and prompt output overlap, corrupting the terminal display. Always call `spinner.stop()` first.
- **Using `require()` with @clack/prompts v1.0+** -- the package is ESM-only since v1.0. Use `import` syntax.
**Medium Priority Issues:**
- **Not using `group()` for multi-step flows** -- checking `isCancel()` after every single prompt is verbose and error-prone. `group()` with `onCancel` centralizes this.
- **Ignoring the `validate` option** -- prompts accept invalid input by default. Add validation for any input that has constraints.
- **Using `multiselect` without `required: false` when zero selections should be valid** -- by default, at least one item must be selected.
**Gotchas & Edge Cases:**
- `isCancel()` returns `true` for the cancel symbol but also narrows the TypeScript type -- always use it as a type guard before accessing the value
- `spinner()` returns an object, not a promise -- call `.start()` separately
- `group()` prompt functions receive `{ results }` with all previously collected values, but TypeScript types each value as possibly undefined since earlier prompts might not have run yet
- `confirm()` returns `boolean | symbol`, not just `boolean` -- still needs `isCancel()` check when used outside `group()`
- `select()` generic type parameter controls the return type -- `select<"react" | "vue">({...})` narrows the result
- `log.warn` has an alias `log.warning` -- both work identically
- `progress.advance()` with no arguments advances by 1 -- the step parameter is optional
- `note()` and `box()` are synchronous (not prompts) -- they return `void`, not promises
- All prompts accept `signal: AbortSignal` for programmatic cancellation (e.g., timeouts)
- `updateSettings()` applies globally -- call it once at startup, not per prompt
- v1.1.0 replaced `picocolors` with Node.js built-in `styleText` -- requires Node.js 20.12+
</red_flags>
---
<critical_reminders>
## CRITICAL REMINDERS
> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)
**(You MUST check `isCancel()` after EVERY prompt call -- skipping this causes silent crashes when users press Ctrl+C)**
- **(You MUST call `process.exit(0)` after `cancel()` -- the cancel message prints but the process keeps running otherwise)**
+ **(You MUST exit the process after `cancel()` -- the cancel message prints but execution continues otherwise)**
+
+ **(You MUST exit with a NON-ZERO code on cancellation, taking the value from the CLI framework's exit-code table where one exists and using 130 where none does -- exiting 0 tells every caller the work succeeded)**
**(You MUST use `group()` with `onCancel` for multi-step flows -- it handles cancellation centrally so you don't check each prompt individually)**
**(You MUST call `spinner.stop()` before any other output -- overlapping spinner output with prompts or logs corrupts the terminal)**
**Failure to follow these rules will cause silent process hangs, corrupted terminal output, and runtime crashes on user cancellation.**
</critical_reminders>