CLI · caret add

caret add

Copies the files for a single component (and any peer files it declares) into the current project. Files are physical sources — no symlinks, no node_modules dependency, no version bookkeeping. After add, you own the code.

Usage

caret add <component> [--dir <path>]
# or
npx caret-cli add <component>

Flags

Flag	Default	Description
--dir <path>	caret/	Target directory (relative to cwd)

Where files come from

The CLI ships its own copy of the registry inside the npm tarball. At add time it searches three locations in order:

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

First location applies to virtually every consumer.

Example

$ caret add prompt
^ Adding prompt
  text, password, confirm, select, multi-select, number

  + caret/components/prompt/index.tsx
  + caret/components/prompt/shared.tsx
  + caret/components/prompt/text.tsx
  + caret/components/prompt/password.tsx
  + caret/components/prompt/confirm.tsx
  + caret/components/prompt/select.tsx
  + caret/components/prompt/multi-select.tsx
  + caret/components/prompt/number.tsx

✓ 8 file(s) written

Required dependencies:
  npm install ink react

See specs/prompt.md for the full specification.

Runtime dependencies

Each component declares its runtime deps in the registry manifest. add prints them after the copy completes — install once per project, reuse for every subsequent add:

Common dep	Used by
ink, react	Every interactive component (prompt.*, spinner, form, modal, search, pager, toast)
chalk	Every component that emits color (most of them)
figlet	splash, logo, textToArt
jimp	imageToArt only
qrcode	qrcode component only

Re-running add

Running add for a component you already have copies the latest version on top of your local files. Diff first if you've modified the component — Caret won't ask before overwriting.

⚠Local edits get overwritten

Treat caret add like shadcn add — useful for the first installation, intentional and version-controlled afterwards. If you've forked a component, run git diff before you re-add.

Custom destination

caret add error --dir src/ui
# writes:  src/ui/components/error.ts

Exit codes

Code	Meaning
0	All files copied successfully
1	Unknown component, missing file, or IO error

See caret list for the full component catalog.