CLI reference

Run the CLI without installing it globally:

npx @better-push/cli <command>

To use the shorter local binary form, install @better-push/cli as a development dependency and run pnpm exec better-push <command>.

Commands

Command	Purpose
`init`	Detect the stack and scaffold the integration
`migrate`	Apply the canonical tables and indexes
`generate`	Write schema files for your migration tool
`doctor`	Diagnose code, environment, schema, and runtime wiring
`dev`	Run the local emulator inbox
`add`	Copy owned UI components into the application
`studio`	Run the operator Studio against a database

The CLI sends no telemetry and performs no version check.

Scaffold with `init`

npx @better-push/cli init

init detects the framework, database client, package manager, source layout, and import aliases. It previews file and environment changes, requests confirmation, and skips existing files unless --force is set. It never changes the database.

Option	Effect
`--framework <next\|tanstack\|express\|hono\|nestjs>`	Override framework detection
`--orm <drizzle\|prisma\|postgres>`	Override database-client detection
`--cwd <dir>`	Target another project directory
`--dry-run`	Preview without writing
`--yes`, `-y`	Skip confirmation
`--force`	Allow existing generated files to be replaced

The generated mount depends on the framework; the schema artifact depends on the database client.

Framework	Generated mount
Next.js	App Router catch-all route
TanStack Start	Splat server route
Express	`Router` mounted with `app.use()`
Hono	Sub-application mounted with `app.route()`
NestJS	Module imported by the application

Manage the schema

Choose one schema owner. Both approaches produce the same bp_* tables and indexes.

Apply the canonical schema

npx @better-push/cli migrate

The command resolves the connection string from --database-url, DATABASE_URL, .env.local, or .env. It uses idempotent DDL and asks for confirmation before connecting to a non-local database.

Option	Effect
`--database-url <url>`	Override the resolved connection string
`--dry-run`	Print SQL without connecting
`--yes`	Skip confirmation for a non-local database
`--cwd <dir>`	Change where environment files are read

Use the application's migration tool

npx @better-push/cli generate

Client	Generated artifact
Drizzle	TypeScript schema for `drizzle-kit`
Prisma	Prisma models and a required partial-index SQL file
`pg`	Canonical SQL

Options: --orm overrides detection, --out changes the single-file output, --stdout prints instead of writing, and --force replaces existing output. Prisma cannot express the required partial indexes in its schema language, so apply the generated SQL after the Prisma migration.

Diagnose with `doctor`

npx @better-push/cli doctor

Static checks inspect the project layout, route mount, service worker, and environment. When the configuration can be loaded, live checks inspect the schema, providers, session resolver, queue, cache, digests, and retention.

doctor exits with status 1 if it finds an error. Use --json for structured output, --config <path> to select the module exporting the better-push instance, and --cwd <dir> to inspect another project.

The same read-only diagnostics are available in application code:

const result = await push.diagnose();
if (result.summary.error > 0) {
  console.error(result.findings);
}

Run development tools

Emulator inbox

npx @better-push/cli dev
npx @better-push/cli dev --port 4984

The inbox binds to 127.0.0.1 and has no authentication. Add the development-only emulator() provider and follow the emulator guide to register a virtual device.

Copy UI components

npx @better-push/cli add --list
npx @better-push/cli add notification-bell

Use --dir <path> to choose the component directory and --force to replace an existing component. The copied source becomes part of your application; see UI components.

Local Studio

npx @better-push/cli studio

Studio binds to 127.0.0.1:4983 and is read-only by default. --allow-writes enables operator actions, --port changes the port, and --database-url overrides database discovery. See Run Studio locally.

Diagnostic result

Prop

Type

Prop

Type

On this page