---
title: Getting Started
description: Learn how to get started with Clack
---

import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';

Clack is a modern, flexible and powerful CLI library that helps you build beautiful command-line interfaces with ease. It provides a set of high-level components and low-level primitives that make it simple to create interactive command-line applications.

## Features

- 🎨 Beautiful, modern UI components
- 🎯 Type-safe with full TypeScript support
- 🎭 Customizable styling and theming
- 🎮 Interactive prompts and menus
- 🎪 Progressive disclosure
- 🎭 Form validation
- 🎯 Error handling
- 🎨 Consistent styling
- 📦 ESM-first distribution

## Installation

You can install Clack using npm, yarn, or pnpm:

<Tabs>
	<TabItem label="npm" icon="seti:npm">
		```bash
		npm install @clack/prompts
		```
	</TabItem>
	<TabItem label="pnpm" icon="pnpm">
		```bash
		pnpm add @clack/prompts
		```
	</TabItem>
	<TabItem label="Yarn" icon="seti:yarn">
		```bash
		yarn add @clack/prompts
		```
	</TabItem>
</Tabs>

## Quick Start

Here's a simple example to get you started:

```ts twoslash
import { text, select, confirm, isCancel } from '@clack/prompts';

async function main() {
  // Get user's name
  const name = await text({
    message: 'What is your name?',
    placeholder: 'John Doe',
  }) as string;

  // Get user's preferred framework
  const framework = await select({
    message: 'Choose a framework:',
    options: [
      { value: 'react', label: 'React' },
      { value: 'vue', label: 'Vue' },
      { value: 'svelte', label: 'Svelte' },
    ],
  });

  if (isCancel(framework)) {
    console.log('Operation cancelled');
    process.exit(0);
  }

  // Confirm the selection
  const shouldProceed = await confirm({
    message: `Create a ${framework} project for ${name}?`,
  });

  if (shouldProceed) {
    console.log('Creating project...');
  }
}
```

## Core Concepts

### High-Level Components

Clack provides several high-level components that make it easy to build interactive CLIs:

- `text()` - For text input with validation
- `multiline()` - For multi-line text input
- `password()` - For secure password input with masking
- `select()` - For selection menus
- `selectKey()` - For choosing an option by pressing its key
- `confirm()` - For yes/no confirmations
- `multiselect()` - For multiple selections
- `groupMultiselect()` - For grouped multiple selections
- `autocomplete()` - For searchable selection menus
- `path()` - For file/directory path selection with autocomplete
- `date()` - For structured date entry (YMD / MDY / DMY)
- `note()` - For displaying information
- `box()` - For boxed text display
- `spinner()` - For loading states
- `progress()` - For progress bar display
- `tasks()` - For sequential task execution
- `taskLog()` - For log output that clears on success
- `stream` - For multi-line streamed output (async iterators, readable streams)

### Low-Level Primitives

For more control, you can use the low-level primitives:

```ts twoslash
import { TextPrompt, isCancel } from '@clack/core';

const p = new TextPrompt({
  render() {
    return `What's your name?\n${this.value ?? ''}`;
  },
});

const name = await p.prompt();
if (isCancel(name)) {
  process.exit(0);
}
```

## Next Steps

1. Check out our [Examples](/docs/clack/guides/examples) for more practical use cases
2. Learn about [Best Practices](/docs/clack/guides/best-practices) for building CLIs
3. Explore the [API Reference](/docs/clack/packages/prompts) for detailed documentation
4. Join our [Discord community](https://bomb.sh/chat) for support and discussions

## TypeScript Support

Clack is built with TypeScript and provides full type safety. All components and primitives are properly typed, making it easy to catch errors at compile time.

```ts twoslash
import { text } from '@clack/prompts';

// TypeScript will ensure the validation function returns the correct type
const age = await text({
  message: 'Enter your age:',
  validate: (value) => {
    if (!value) return 'Please enter a value';
    const num = parseInt(value);
    if (isNaN(num)) return 'Please enter a valid number';
    if (num < 0 || num > 120) return 'Age must be between 0 and 120';
    return undefined;
  },
});
```

## Contributing

We welcome contributions! Please check out our [Contributing Guide](/contributing) for details on our code of conduct and the process for submitting pull requests.
