# @stacksjs/clapp

> A toolkit for building CLI prompts in TypeScript.

Latest version **0.2.16** (published 2026-09-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @stacksjs/clapp
pnpm add @stacksjs/clapp
yarn add @stacksjs/clapp
bun add @stacksjs/clapp
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.16 |
| Published | 2026-09-08 |
| First published | 2025-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 221.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 14 |
| Author | Chris Breuer <chris@stacksjs.org> |
| Maintainers | chrisbreuer, glenn123 |
| Keywords | cli, prompts, toolkit, typescript, stacks |

## Links

- npm: https://www.npmjs.com/package/@stacksjs/clapp
- Repository: https://github.com/stacksjs/clapp
- Homepage: https://github.com/stacksjs/clapp#readme
- Issues: https://github.com/stacksjs/clapp/issues
- npm.io page: https://npm.io/package/@stacksjs/clapp

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.2.16 (latest) — 2026-09-08
- 0.2.15 — 2026-08-28
- 0.2.14 — 2026-08-28
- 0.2.13 — 2026-08-13
- 0.2.12 — 2026-07-21
- 0.2.11 — 2026-07-21
- 0.2.10 — 2026-05-14
- 0.2.9 — 2026-05-11
- 0.2.8 — 2026-05-06
- 0.2.7 — 2026-05-04
- 0.2.6 — 2026-05-02
- 0.2.5 — 2026-05-02
- 0.2.4 — 2026-05-02
- 0.2.3 — 2026-05-02
- 0.2.0 — 2025-08-31
- … 11 more at https://npm.io/package/@stacksjs/clapp/versions

## README

# @stacksjs/clapp

An elegant, TypeScript-first CLI framework built on Bun for creating beautiful command-line applications with interactive prompts.

## Installation

```bash
bun add @stacksjs/clapp -d
# or
npm install @stacksjs/clapp --save-dev
```

## Usage

### Interactive Prompts

Create beautiful, interactive command-line experiences with pre-styled prompt components:

```typescript
import { confirm, intro, multiselect, outro, select, spinner, text } from '@stacksjs/clapp'

intro('Project Setup Wizard')

const name = await text({
  message: 'What is your project name?',
  placeholder: 'my-awesome-project',
  validate(value) {
    if (value.length === 0)
      return 'Name is required!'
  },
})

const useTypeScript = await confirm({
  message: 'Do you want to use TypeScript?',
})

const framework = await select({
  message: 'Select a framework:',
  options: [
    { value: 'react', label: 'React' },
    { value: 'vue', label: 'Vue', hint: 'recommended' },
    { value: 'svelte', label: 'Svelte' },
  ],
})

const features = await multiselect({
  message: 'Select additional features:',
  options: [
    { value: 'router', label: 'Router' },
    { value: 'state', label: 'State Management' },
    { value: 'testing', label: 'Testing' },
  ],
  required: false,
})

const s = spinner()
s.start('Installing dependencies')
await new Promise(resolve => setTimeout(resolve, 2000))
s.stop('Installation complete!')

outro('You are all set!')
```

### CLI Framework

Build robust command-line applications with an elegant API:

```typescript
import { CLI } from '@stacksjs/clapp'

const cli = new CLI('greet')
  .version('1.0.0')
  .help()

cli.command('hello <name>', 'Greet a user')
  .option('--shout', 'Uppercase the greeting')
  .action((name, opts) => {
    const line = `Hello, ${name}!`
    console.log(opts.shout ? line.toUpperCase() : line)
  })

// `run()` catches usage errors (unknown flags, missing args), prints a
// friendly message, and exits with code 2. Non-usage errors propagate.
await cli.run()
```

### Usage-error handling

Running `greet hello --nope` prints:

```
greet: Unknown option `--nope`

Run `greet hello --help` to see available options.
```

…and exits with code `2` — no stack trace.

Three levels of integration:

```typescript
// 1. Highest level — `run()` handles usage errors for you.
await cli.run()

// 2. Same behaviour as an option on `parse()`.
await cli.parse(process.argv, { exitOnError: true })

// 3. DIY — catch and delegate to the same renderer.
try {
  await cli.parse(process.argv)
}
catch (err) {
  cli.handleUsageError(err)  // prints + exits for ClappError usage errors
  throw err                  // rethrows non-usage errors
}
```

`ClappError` instances expose:

- `isUsageError: boolean` — `true` for "the user typed it wrong", `false` for internal failures.
- `exitCode: number` — defaults to `2` for usage errors; override for specific error classes.

### Telemetry

Optional telemetry support for tracking CLI usage:

```typescript
import { createTelemetry } from '@stacksjs/clapp/telemetry'

const telemetry = createTelemetry({
  // configuration
})
```

## Features

- Beautiful interactive prompts (text, confirm, select, multiselect, spinner)
- Powerful CLI command framework
- TypeScript-first with full type safety
- Bun-powered for fast execution
- Optional telemetry support

## License

MIT

---
_Source: https://npm.io/package/@stacksjs/clapp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._