tulipfarm docsReference
Commands
The scripts that set up, run, and check a TulipFarm checkout.
TulipFarm is a pnpm + Turborepo monorepo. Run these from the repository root unless
noted. The package manager is pnpm — do not substitute npm or yarn.
Setup
| Command | What it does |
|---|---|
bash scripts/setup-dev.sh | Installs PostgreSQL 17 + pgvector, starts the database, creates the tulipfarm database, initializes the soul repo at ~/.tulipfarm/soul, and writes .env.local with generated secrets. |
pnpm install | Installs workspace dependencies. Use --frozen-lockfile in CI. |
pnpm reset:dev | Tears down the local dev database and soul, then re-runs setup. Use when you want a clean slate. |
Run
| Command | What it does |
|---|---|
pnpm dev | Starts the API (:4010) and web UI (:4000) together. |
pnpm dev:api | Starts only the API. |
pnpm dev:web | Starts only the web UI. |
pnpm dev:docs | Starts this documentation site (:4020). |
curl http://localhost:4010/health | Checks API health; returns { "status": "ok" }. |
Build and check
| Command | What it does |
|---|---|
pnpm build | Builds every workspace through Turbo. |
pnpm lint | Runs Biome across all workspaces. |
pnpm typecheck | Runs tsc --noEmit across all workspaces. |
pnpm test | Runs the Vitest suites. |
Single workspace
Target one workspace with a filter:
pnpm --filter @tulipfarm/api dev
pnpm --filter @tulipfarm/web test
pnpm --filter @tulipfarm/docs buildSecrets and encryption
These run against a local or production instance. They read .env.local and DATABASE_URL.
| Command | What it does |
|---|---|
pnpm --filter @tulipfarm/api keys verify | Checks that the active DEK unwraps correctly under the current ENCRYPTION_KEY. Run after a key rotation to confirm the new key works. |
pnpm --filter @tulipfarm/api keys show-recovery | Mints the offline recovery key and prints it once. Store it in a password manager or sealed vault — it is never shown again. |
pnpm --filter @tulipfarm/api keys rotate-kek | Re-wraps the DEK under the new ENCRYPTION_KEY. Requires both ENCRYPTION_KEY (new) and ENCRYPTION_KEY_PREVIOUS (old) to be set. |
pnpm --filter @tulipfarm/api keys recover | Recovers a lost ENCRYPTION_KEY using the offline recovery key. Set RECOVERY_KEY=<base64> in the environment before running. |
pnpm --filter @tulipfarm/api keys backfill | Migrates secrets written before envelope encryption onto the DEK. Idempotent and resumable. |