CLI

BTST has two CLI packages:

• @btst/codegen owns init scaffolding (npx @btst/codegen init)
• @btst/cli owns low-level DB schema generation and migrations

@btst/codegen generate and @btst/codegen migrate are passthrough entrypoints to the existing @btst/cli flow.

Init (Codegen)

Use init to scaffold BTST into an existing Next.js (App Router), React Router v7, or TanStack Start project:

npx @btst/codegen init

Common flags:

init scaffolds and patches:

• lib/stack.ts (or framework equivalent)
• lib/stack-client.tsx
• lib/query-client.ts
• API catch-all route and pages catch-all route
• Global CSS imports (including plugin CSS)
• Root layout with QueryClientProvider where possible

If root layout patching is not safe for your file shape, the command prints manual patch instructions instead of applying a destructive rewrite.

Generated plugin config entries in lib/stack.ts and lib/stack-client.tsx use camelCase config keys (for example aiChat, uiBuilder, formBuilder) even though plugin selection flags use kebab-case names.

Generate and Migrate via Codegen

If you prefer one command surface, these delegate to @btst/cli:

npx @btst/codegen generate --orm=prisma --config=lib/stack.ts --output=schema.prisma
npx @btst/codegen migrate --config=lib/stack.ts --database-url=postgres://...

When a delegated command fails, fix the underlying issue and run the equivalent npx @btst/cli ... command directly.

About Better DB

BTST uses Better DB (@btst/db) as its database abstraction layer—a specialized fork of better-auth's database layer optimized for BTST's plugin architecture.

The CLI works with the dbSchema exported from your BTST configuration, which is built using Better DB's schema definition API. All plugin schemas are automatically merged into a unified schema that the CLI can process.

Install the CLI as a dev dependency:

npm install -D @btst/cli

pnpm add -D @btst/cli

yarn add -D @btst/cli

Parameters

Generate

Generate database schemas for your ORM from your BTST dbSchema:

npx @btst/cli generate --config=lib/stack.ts --orm=prisma --output=schema.prisma

npx @btst/cli generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts

DATABASE_URL=sqlite:./dev.db npx @btst/cli generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql

npx @btst/cli generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=sqlite:./dev.db

npx @btst/cli generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=postgres://user:pass@localhost:5432/db

Migrate

Migrate your database schema directly (Kysely only). For Prisma and Drizzle, use their native migration tools.

Using DATABASE_URL environment variable:

DATABASE_URL=sqlite:./dev.db npx @btst/cli migrate --config=lib/stack.ts

Or using --database-url flag:

npx @btst/cli migrate --config=lib/stack.ts --database-url=sqlite:./dev.db

npx @btst/cli migrate --config=lib/stack.ts --database-url=postgres://user:pass@localhost:5432/db

Generate SQL to File

Instead of running migrations directly, generate SQL to a file:

npx @btst/cli migrate --config=lib/stack.ts --output=migrations.sql --database-url=sqlite:./dev.db

Gotchas

Because the CLI executes your config file to extract the dbSchema, there are a few limitations to be aware of:

• Path aliases don't work: Path aliases (like @/ or ~/) configured in your TypeScript config won't work for any imports used in your stack.ts file or any files it imports. Use relative paths instead.

• Environment variables: If your config file or its imports have conditional checks for available environment variables (e.g., checking if process.env.SOME_VAR exists), you should also pass those environment variables when running CLI commands:

SOME_VAR=value npx @btst/cli generate --config=lib/stack.ts --orm=prisma --output=schema.prisma

or using dotenv-cli:

npx dotenv-cli -e .env.local -- npx @btst/cli generate --orm drizzle --config lib/stack.ts --output db/btst-schema.ts