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 dev
pnpm dev:dashboard
pnpm lint
pnpm format
pnpm check-types
pnpm clean
pnpm ui:add

Use these for normal workspace development:

pnpm build — builds all applications and packages.
pnpm dev — starts development tasks across the monorepo.
pnpm dev:dashboard — starts the dashboard only (Next.js dev server on http://localhost:3000).
pnpm lint — runs lint checks across all applications and packages.
pnpm format — formats all files with Prettier.
pnpm check-types — runs TypeScript type checking for all packages.
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.

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. The nested apps/dashboard/supabase/ folder is deprecated legacy config and should not be used for CLI commands.

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> — creates a baseline or sync migration in supabase/migrations/ from the linked remote state.
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 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:local
pnpm db:types:linked
pnpm db:types:dev

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_DEFAULT_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.
Push to the linked remote project with pnpm db:push only when a manual remote update is intentionally required — otherwise let GitHub Actions deploy the migration through staging or production.

Commands