All docs
Overview · Install

Install

Caret ships as a single npm package: caret-cli. There is no runtime to install in the consumer project — the CLI copies component source files into your repo and exits. Your code never imports from caret-cli at runtime.

Scaffold a new project

Run init with a project name. It creates a directory, writes the starter files, and prints next steps.

sh
npx caret-cli init my-cli
cd my-cli
npm install
npm run dev

What lands in my-cli/:

  • package.json — tsx for dev, tsc for build, ink + react as runtime deps.
  • tsconfig.json — strict mode, ESM, JSX preset for Ink.
  • src/index.ts — a tiny working CLI you can run immediately.
  • caret.md — instruction file for AI assistants. Drop this in your repo root and Claude, Cursor, and Copilot produce correct Caret code on the first try. See AI-native workflow.
  • .gitignore — node_modules, dist, and friends.

Add a single component

Already have a project? Run add with a component name. Files land under caret/ by default; pass --dir for a different target.

sh
npx caret-cli add prompt
npx caret-cli add spinner

# custom destination
npx caret-cli add error --dir src/ui

Each component prints its required runtime dependencies (e.g. ink, react, chalk). Install them once per project; the components themselves are vendored.

ℹOwn the code
Components are not symlinked or imported from caret-cli. They are copied verbatim and live in your repo. Modify, fork, or delete them — Caret is a starting point, not a runtime dependency.

List the registry

See every component the bundled registry exposes:

sh
npx caret-cli list

Output groups components by kind (interactive, display, utility) with a one-line description for each. The full live catalog with previews is at /components.

Registry layout

The CLI ships its own copy of the registry inside the npm tarball. The add command resolves the registry from one of three locations, in order:

  1. Bundled with the package — node_modules/caret-cli/registry/
  2. Workspace dev environment — useful when contributing to Caret itself
  3. Current working directory — for advanced custom registry overrides

The first location applies to virtually every consumer. Each registered component has a manifest entry that lists its files, declared runtime dependencies, and the spec it implements.

Versioning

Caret follows semver. Major bumps may rename or remove components — pin caret-cli with npx -p [email protected] if you need a stable surface during a refactor. Components copied into your repo are frozen at the version you ran add with; re-run to upgrade.