/cli-prompts-clack

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. `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 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.

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(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, the exit stops dangling execution, the non-zero code stops callers from reading an abandoned run as a completed one

// 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