/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. 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 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";

p.intro("Project setup");

const name = await p.text({ message: "Project name?" });

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

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

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

---

Pattern 2: Group Prompts with Centralized Cancellation

`group()` chains multiple prompts and handles cancellation in one place. Each prompt receives previous results.

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);
    },
  },
);

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

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.

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 in