CLI · caret init

caret init

Creates a new directory with a runnable starter project: a typed entry file, a tsconfig, an AI-instruction file, and a .gitignore. After init, the project compiles and runs out of the box.

Usage

caret init <name>
# or
npx caret-cli init <name>

Files written

File	Purpose
package.json	tsx for dev, tsc for build, ink + react as runtime deps
tsconfig.json	Strict mode, ESM, JSX preset compatible with Ink
src/index.ts	Tiny working CLI you can run immediately
caret.md	AI-instruction file — Claude / Cursor / Copilot read this on every interaction
.gitignore	node_modules, dist, *.log, .env

What the starter index looks like

src/index.ts

#!/usr/bin/env node

console.log('Hello, Caret!')
console.log('Run `npx caret add prompt` to add your first component.')

It's intentionally tiny. The first caret add is what turns this into a real Caret CLI — until then there are no components to import.

Why caret.md ships at init time

Modern CLIs are mostly written by AI assistants. The caret.md file at your repo root is a short, opinionated rule book that tells Claude / Cursor / Copilot exactly how to use Caret on the first try. Without it the LLM produces chalk + ora code from its training set; with it, the same prompt produces idiomatic Caret.

See AI-native workflow for what's in the file and how to extend it with your own rules.

⚠Target directory must not exist

If ./<name>/ already exists, init aborts with exit code 1. Pick a fresh path or remove the existing directory first. Init will not overwrite a project in flight.

After init

cd my-cli
npm install
npm run dev          # tsx src/index.ts

npx caret add prompt
npx caret add spinner

Exit codes

Code	Meaning
0	Project scaffolded successfully
1	Target directory exists, no name supplied, or IO error

Continue with caret add.