Referenta Docs | Commands

Root-level development commands for local Supabase workflows, migration generation, type generation, and monorepo development.

All commands are run from the repo root unless noted. They are grouped by what they actually do day-to-day.

Monorepo Commands

pnpm build
pnpm build:dashboard
pnpm build:www
pnpm build:cms
pnpm dev
pnpm dev:dashboard
pnpm dev:www
pnpm dev:cms
pnpm dev:presidio
pnpm dev:kreuzberg
pnpm dev:gotenberg
pnpm dev:press
pnpm format-and-lint
pnpm format-and-lint:fix
pnpm lint
pnpm check-types
pnpm test
pnpm clean
pnpm ui:add
pnpm translate:dashboard

Use these for normal workspace development:

pnpm build — builds all applications and packages.
pnpm build:dashboard — builds only the dashboard app.
pnpm build:www — builds only the marketing site.
pnpm build:cms — builds only the CMS app.
pnpm dev — starts development tasks across the monorepo.
pnpm dev:dashboard — starts the dashboard only (Next.js dev server on http://localhost:3000).
pnpm dev:www — starts the marketing site only.
pnpm dev:cms — starts the CMS app only.
pnpm dev:presidio — starts the Presidio PII-masking service only.
pnpm dev:kreuzberg — starts the Kreuzberg document-extraction service only.
pnpm dev:gotenberg — starts the Gotenberg PDF/document-generation service only.
pnpm dev:press — starts the Press Monitor API service only.
pnpm format-and-lint — runs biome check . across the repo. Biome is the sole authoritative formatter and linter (pre-commit hook and CI both run it); there is no Prettier and no ESLint.
pnpm format-and-lint:fix — the same, with --write to apply fixes.
pnpm lint — runs each workspace's own lint task through Turborepo. Useful for scoping to one package; format-and-lint is what CI gates on.
pnpm check-types — runs TypeScript type checking for all packages.
pnpm test — runs the Vitest suites (co-located *.test.ts(x)). The Playwright e2e suite is separate: pnpm --filter=dashboard test:e2e.
pnpm clean — removes node_modules and build output from all applications and packages.
pnpm ui:add — adds a new component to the @referenta/ui package. See the shadcn/ui components list for available components.
pnpm translate:dashboard — runs the dashboard's lingo.dev translation sync (pnpm translate, scoped to the dashboard workspace) to update dictionaries/*.json.

Environment Commands

pnpm env:pull

pnpm env:pull — pulls Vercel-managed development environment variables into the right .env files. Run this after vercel link --repo.

Local Supabase Commands

The supported Supabase CLI project lives in the repo root supabase/ directory.

pnpm db:start
pnpm db:stop
pnpm db:status
pnpm db:status:env
pnpm db:reset
pnpm db:pull -- <name>
pnpm db:push

What each one does:

pnpm db:start — starts the local Docker-managed Supabase stack from the repo root.
pnpm db:stop — stops the local Supabase stack.
pnpm db:status — shows local Supabase URLs and service status.
pnpm db:status:env — prints local Supabase env values for apps/dashboard/.env.local.
pnpm db:reset — resets the local database, re-runs migrations and seed files, and re-creates the local-only role accounts.
pnpm db:pull -- <name> — writes the linked remote's state into a new migration file. Not part of onboarding — the history is already committed, so a fresh clone only needs pnpm db:reset. Reach for this only to capture state that legitimately diverged on hosted (e.g. a change applied through the Supabase dashboard).
pnpm db:push — manually pushes local migrations to the linked hosted dev project. Only use this when an explicit manual push is required; normally migrations reach hosted environments through Supabase Branching (preview → staging → production), not GitHub Actions.

Migration Commands

pnpm db:diff <name>
pnpm migration:new -- <name>
pnpm migration:up

pnpm db:diff <name> — diffs the declarative schema in supabase/schemas/ into a named migration file in supabase/migrations/.
pnpm migration:new -- <name> — creates an empty migration file when you need to write SQL by hand instead of generating from a schema diff.
pnpm migration:up — applies pending migrations to the local database.

Type Generation Commands

pnpm db:types
pnpm db:types:local
pnpm db:types:linked
pnpm db:types:dev

pnpm db:types — alias for pnpm db:types:local.
pnpm db:types:local — regenerates TypeScript types from the local Supabase stack.
pnpm db:types:linked — regenerates types from the currently linked remote project.
pnpm db:types:dev — regenerates types from the shared hosted dev project.

Regenerate types after migrations so the dashboard's TypeScript code stays aligned with the database schema.

Environment Variable Mapping

When pointing the dashboard at local Supabase, copy apps/dashboard/.env.local.example to apps/dashboard/.env.local and map values from pnpm db:status:env like this:

API_URL -> NEXT_PUBLIC_SUPABASE_URL
ANON_KEY -> NEXT_PUBLIC_SUPABASE_ANON_KEY
PUBLISHABLE_KEY -> NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
SERVICE_ROLE_KEY -> SUPABASE_SERVICE_ROLE_KEY

In practice the local URL value is:

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321

Keep local values in apps/dashboard/.env.local. Use pnpm env:pull when you want the hosted Vercel-managed environment variables again.

Recommended Flow

For typical database work:

Start local services with pnpm db:start.
Reset and seed with pnpm db:reset.
Point apps/dashboard/.env.local to the local stack using values from pnpm db:status:env.
Run the app with pnpm dev:dashboard.
Edit the matching file in supabase/schemas/, then generate a migration with pnpm db:diff <name>.
Apply it locally with pnpm migration:up.
Regenerate types with pnpm db:types:local if the schema changed.
Open a PR against dev and merge it — Supabase Branching applies the migration to staging on merge to dev, and to production on merge to main via a Release Candidate PR. GitHub Actions never deploys migrations. Reach for pnpm db:push only when an intentional manual push to the linked hosted dev project is required.

Commands