CLI

@beignet/cli creates Beignet apps, generates feature slices and workflow artifacts, runs database and operational entrypoints, inspects route wiring, and catches drift after manual edits. Use Quickstart to create and run your first app; use this page as the command reference.

Scaffold a new app through your package manager's create command. Inside a generated app, @beignet/cli is already a dev dependency with a beignet package script. Or run the scoped package without installing:

bun create beignet my-app

bun beignet lint
npm run beignet -- lint

bunx @beignet/cli doctor --strict
npx @beignet/cli doctor --strict

Always pass the scoped name (@beignet/cli) to bunx, npx, pnpm dlx, or yarn dlx — the unscoped npm name beignet belongs to an unrelated package. Reference blocks below show the bare beignet <command> syntax; prefix it with your package manager. beignet --version prints the installed CLI version.

Commands

create

bun create beignet my-app

In an interactive terminal without selection flags, create prompts for the project directory, whether the app is API-only, which database to use, and which integrations to add. A selection flag (--api, --db, or --integrations) skips the prompts, --yes forces the defaults, and non-TTY environments never see prompts. There is one full-stack starter; --api drops the UI shell and app pages while keeping the same architecture, and --db picks the database backend (sqlite by default). The CLI writes files only — see Quickstart for what the starter contains and the install, environment, migrate, and first-run steps, and Database and transactions for what each --db backend scaffolds.

Better Auth, Drizzle persistence, Pino, and no-op error reporting are part of every starter, so passing them to --integrations is an error. Integrations add external service providers on top: the provider package, peer dependencies, wiring in server/providers.ts, .env.example entries, and setup notes in docs/integrations.md.

--integrations also accepts the full providers add preset catalog. Presets are applied to the fresh scaffold with the same machinery as beignet providers add, so create-time and post-create setup stay identical; examples include event-bus-redis, redis-cache, jobs-bullmq, s3-storage, and search-meilisearch. Preset names with a template equivalent (jobs-inngest, mail-resend, upstash-rate-limit) normalize to the template integration, and selections that fill the same app port (for example resend plus mail-smtp) fail before any files are written. The interactive prompt keeps the short template list and points at the wider catalog.

make

Generators run inside an app and target the canonical structure described in App architecture. All of them — along with routes, lint, and doctor — resolve beignet.config.* (.ts, .json, .mjs, or .js) path overrides first; omitted paths fall back to the generated defaults. The same config can declare app-owned operational table names, such as database.tables.audit: "audit_events", so doctor checks Drizzle-backed audit, idempotency, and outbox wiring against the names your app uses. Add database.schemaSources when those table definitions live in a shared package or non-standard app path, for example ["@acme/db/schema"]. Generators are idempotent: repeated runs skip identical files and avoid duplicate wiring, and a generated file that diverged stops the command unless you pass --force.

Every make command accepts:

make feature

beignet make feature projects

Generates the contract-first vertical slice for a product capability: contracts.ts, schemas.ts, use-cases/, ports.ts, routes.ts, a test file, and a Drizzle repository adapter. It registers the route group in server/routes.ts, the port in ports/index.ts, and the repository in infra/db/repositories.ts; OpenAPI routes that use route registration stay in sync automatically. The generated name field is a placeholder — reshape the slice around the real workflow.

Each addon writes the same output as the matching standalone generator; ui writes a feature-colocated React component wired to the typed client and TanStack Query.

Use --recipe full-slice when you want a richer reference slice:

beignet make feature projects --recipe full-slice

The recipe keeps the base contracts.ts, schemas.ts, use-cases/, ports.ts, routes.ts, and tests, then adds feature-owned workflow artifacts around them. The generated create use case publishes the generated ProjectCreated event, and the event/job generators add server/outbox.ts, infra/db/schema/outbox-messages.ts, the outbox drain route, and the required port wiring. The listener generator registers the feature listener registry in server/listeners.ts and wires the central listener provider in server/providers.ts. Replace the starter name field, logger messages, listener body, job body, notification payload, and task body with the real workflow. When the workflow needs durable audit records, follow Audit and activity logging and record the business action inside the same Unit of Work transaction as the write.

make resource

beignet make resource projects
beignet make resource projects --auth --tenant --events --soft-delete

Generates a CRUD-shaped slice when the concept is an entity with repository-backed persistence: list, create, get, update, and delete contracts, use cases, route handlers, repository methods, a policy starter, tests, feature-specific not-found and conflict catalog errors, a Drizzle schema file, and repository registration. Generated list endpoints use cursor pagination, and updates use optimistic concurrency version checks that turn stale writes into the generated conflict error. See Build your first feature for the guided flow.

--events also wires the event bus when the app has none, exactly like make event (see workflow generators below).

make contract

beignet make contract projects

Writes features/projects/contracts.ts with a starter contract group, schema, and standard error response. It does not wire routes, use cases, or ports — use make feature for the full slice. See Contracts.

make use-case and make test

beignet make use-case projects/archive-project
beignet make test projects/archive-project

make use-case writes features/projects/use-cases/archive-project.ts and updates the use-case index; actions starting with get, list, find, search, or count generate .query(...), others .command(...). make test writes features/projects/tests/archive-project.test.ts using the test context helpers. See Application and Testing.

make port, make adapter, and make policy

beignet make port email
beignet make adapter email
beignet make policy posts

make port writes ports/email.ts, adds the port to AppPorts, creates a test fake, and wires a throwing infra stub so the app still typechecks. make adapter writes infra/email/email-adapter.ts and replaces the stub; it stops instead of guessing when the infra wiring was customized. make policy writes features/posts/policy.ts with a definePolicy(...) starter. See Ports and Authorization.

Workflow generators

beignet make event posts/published
beignet make listener posts/enqueue-published-email --event posts/published
beignet make job posts/send-published-email
beignet make notification posts/published
beignet make outbox
beignet make schedule posts/daily-summary --cron "0 9 * * *" --timezone America/Chicago --route
beignet make task posts/backfill-search
beignet make upload posts/attachment

Names use feature/name format. Each generator writes the colocated feature file (for example features/posts/jobs/send-published-email.ts), creates or updates the folder's registry index.ts (postEvents, postJobs, and so on), and creates the matching app-bound lib/ builder such as lib/jobs.ts on first use. New apps do not scaffold workflow folders; generators create them on demand. They also keep central registries and ports wired:

• make schedule and make task create or update the server/schedules.ts and server/tasks.ts registries used by the runners below.
• make listener creates or updates the server/listeners.ts registry and wires that central registry with registerListeners(...).
• make outbox creates server/outbox.ts and a bounded app/api/cron/outbox/drain route. make event and make job create that outbox path on first use and append the feature's registries to defineOutboxRegistry({...}). See Outbox.
• make event and make resource --events wire eventBus: EventBusPort into AppPorts, register createMemoryEventBusProvider() in server/providers.ts, and add the @beignet/provider-event-bus-memory dependency when the ports file lacks the key.
• make notification wires mailer: MailerPort with createMemoryMailerProvider() and notifications: NotificationPort with createInlineNotificationsProvider(), each independently and only when missing, so integrations such as resend and app-owned adapters are left untouched. Swap the dev-default providers when you outgrow them.
• make listener requires --event and expects the event file to exist; run make event first.
• make schedule --route writes app/api/cron/<feature>/<name>/route.ts, which requires CRON_SECRET, and adds a generated CRON_SECRET to lib/env.ts and .env.example when the app does not define one.

Concept pages: Events, Jobs, Schedules, Notifications, and Uploads. Operational tasks are app-owned entrypoints for backfills, maintenance, and one-off repair work; they should call use cases or ports rather than copying business rules into scripts.

make factory and make seed

beignet make factory posts/post
beignet make seed posts/demo-posts

make factory writes features/posts/tests/factories/post.ts plus a factory registry; the starter persists through repository ports. make seed writes features/posts/seeds/demo-posts.ts plus a seed registry, creates the app-owned server/seed.ts entrypoint when it is missing, and adds the db:seed script. The entrypoint lives in server/ because it boots the app through getServer(), which beignet lint forbids from infra/. See Database.

make tenancy

beignet make tenancy
beignet db generate
beignet db migrate

Generates a workspace tenancy slice for Drizzle-backed apps: a features/workspaces feature with contracts, use cases, a membership-aware policy, repositories for workspaces, members, and invites, three Drizzle tables, invite email notifications, tests, and a demo-workspace seed with a sign-in-able demo admin. It replaces the starter lib/tenant.ts and server/context.ts so every request resolves the active workspace from the user's memberships and the beignet-workspace cookie, and adds membership to the app context. On apps with the frontend shell it also emits workspace and member settings pages, an invite accept screen, a workspace switcher, and settings navigation entries.

make tenancy only replaces lib/tenant.ts and server/context.ts when they still match the starter template (or its own output); customized files abort the generator with manual instructions before anything is written, and --force overrides. Routes live under /api/workspaces; switching workspaces sets the beignet-workspace cookie through a route handle escape hatch. See Authorization.

make payments

beignet make payments
beignet db generate
beignet db migrate

Generates a payments-backed billing slice for Drizzle-backed apps: a features/billing feature with a free/pro plan model, FREE_PLAN_LIMITS quotas, a billing-backed entitlements port, a billing_accounts table and repository, checkout/portal/status contracts and use cases, an idempotent app/api/webhooks/payments/route.ts webhook route, a demo billing seed, and BILLING_PRO_PRICE_ID env validation. Local development uses the memory payments provider; swap server/providers.ts to the Stripe provider when credentials are configured. On apps with the frontend shell it also emits a plan settings page at /settings/plan. Billing accounts scope to the user until make tenancy adds workspaces, then become workspace-scoped automatically. See Payments.

make inbox

beignet make inbox
beignet db generate
beignet db migrate

Generates an in-app inbox notifications slice for Drizzle-backed apps: a features/inbox feature with cursor-paginated list, unread-count, mark-read, and mark-all-read contracts and use cases, an inbox_notifications table and repository, an in-app notification channel (defineInboxNotificationChannel), a sample notification, seeds, and tests. The inbox is personal: rows are scoped to the signed-in user and need no tenancy. On apps with the frontend shell it also emits an /inbox page, an unread badge component, and a sidebar navigation entry. Add the in-app channel to any feature notification to deliver into the inbox. See Notifications.

db

beignet db schema sync
beignet db generate
beignet db migrate
beignet db seed
beignet db reset

db schema sync idempotently brings the app-owned Drizzle schema re-exports of Beignet provider tables in sync with the installed providers, currently for Beignet's audit, idempotency, and outbox tables. Run it before db generate when you add those operational ports. Use --tables to sync only the table definitions for the ports in the next migration.

The lifecycle commands (generate, migrate, seed, and reset) delegate to the app-owned package script of the same name (db:generate, db:migrate, db:seed, db:reset) and check prerequisites first — a missing script, missing drizzle.config.*, or removed seed/reset entrypoint produces an error naming the exact file to restore. The starter ships db:generate, db:migrate, and db:reset; run db migrate first since the initial migration is vendored, and add a db:seed script with your first feature seeds. See Database.

routes

beignet routes

Prints a table of method, path, contract export, and matched Next.js handler file for every contract the CLI can inspect. It supports contract-group definitions and direct defineContract({ method, path }) exports.

check

beignet check

Runs the whole validation loop as one command: beignet lint, beignet doctor --strict, and the app's own lint, typecheck, and test package scripts through the detected package manager, in that order. Every step runs even when an earlier one fails, so a single run reports everything that needs fixing, and the command exits non-zero when any step fails. Missing package scripts are reported as skipped, never as failures.

preflight

Runtime production gate, distinct from the static doctor checks: it reads the environment the process actually runs with, so run it in the deploy pipeline where production configuration is present.

beignet preflight
beignet preflight --connect
beignet check --preflight

The gate verifies every env var installed provider manifests mark as required, flags values still matching .env.example (or common placeholder patterns) on secret-like keys, validates the app env schema by importing lib/env.ts, folds in doctor's production hardening diagnostics with promoted severities (doctor warnings fail the gate, hints become warnings), and warns when logging or error reporting is absent or inert. It exits 1 on any error finding.

lint

beignet lint

Enforces the architecture boundaries described in App architecture: it scans static imports across app layers, runs an additional value-import graph check for contracts and client roots, and exits non-zero on findings. Diagnostics include the offending file:line:column.

doctor

beignet doctor
beignet doctor --strict
beignet doctor --fix

The framework integrity report. Diagnostics cover these areas:

• Routes and contracts — contracts without handlers, handlers without contracts, unregistered route groups, partially wired slices, and CRUD slices missing generated pieces.
• OpenAPI — drift in direct arrays, exported contract lists, and contractsFromRoutes(routes) registries, plus entries for contracts outside the registered route surface.
• Workflow registries — schedules and tasks missing from server/schedules.ts or server/tasks.ts, events with listeners and jobs missing from defineOutboxRegistry({...}) when the app uses outbox delivery, listeners missing from server/listeners.ts or otherwise not referenced by registerListeners(...), runtime manifests that omit opted-in workflow registries, and serverless footguns such as background timers in provider files, outbox draining from lifecycle hooks, and outbox registries without a drain entrypoint.
• Errors and authorization — route-owned catalog errors missing from features/shared/errors.ts, runtime appError(...) calls not declared on contracts, authorization metadata without policy coverage, and audit-required metadata without audit writes or test assertions.
• Database — missing Drizzle config, schema exports, scripts, or seed/reset entrypoints, Drizzle-backed idempotency/outbox/audit ports without table setup, provider-declared required tables missing from schema, configured schema sources, or migrations, unwired repository adapters, tenant-scoped Drizzle repository ports or adapters missing TenantScope method arguments, raw tenantId or workspaceId repository boundaries, or tenantScopeId(scope) predicates, ports without adapters, unguarded resets, and seeds without factories or a db:seed script.
• Security and providers — devtools enabled without authorization, cron routes without CRON_SECRET, installed providers without expected env configuration, Better Auth without an auth route or trusted origins, missing security headers, credentialed wildcard CORS, uploads without routes, authorization, or size limits, and notification dispatchers that bypass ctx.ports.notifications.
• Payments — billing slices without a payment webhook route, preferring createPaymentWebhookRoute(...) for payment-port billing, checkout contracts missing idempotency metadata or an idempotency-key header, and billing webhook use cases that reference ctx.ports.idempotency without an AppPorts idempotency declaration, billing entitlement modules that are not wired into infra providers, entitlement checks without an AppPorts entitlements declaration, plus Stripe configuration still wired to local memory payments.
• Structure and versions — feature artifacts in non-canonical folders, strict-mode canonical conformance drift, mixed @beignet/* version ranges or installed versions, and CLI/core version skew (an informational hint suggesting the app-local bun beignet).

When production-readiness diagnostics are present, human doctor output also prints a production hardening checklist covering secrets and provider credentials, verified auth and tenant authority, exposed operational routes, security headers, CORS and proxy trust, upload and storage limits, readiness checks, worker shutdown, webhook secrets, and least-privilege provider credentials.

Workflow artifacts the starter does not scaffold are not drift on their own; doctor reports misplaced, unregistered, or partially wired artifacts, not absent ones.

providers add

beignet providers add redis-cache
beignet providers add s3-storage --dry-run --json

Adds a provider setup preset to an existing app. The command is idempotent: repeated runs skip identical files and avoid duplicate provider entries. It updates package dependencies, server/providers.ts, ports/index.ts, infra/app-ports.ts, .env.example, and docs/integrations.md.

sentry replaces the starter no-op error reporter at provider startup without adding errorReporter to the deferred list. The other presets add their app-facing ports to AppPorts and defer them to provider startup. Presets that fill the same app port, such as mail-resend and mail-smtp, fail with a conflict instead of registering competing providers. Provider escape hatches such as ctx.ports.redis, ctx.ports.redisEventBus, ctx.ports.redisLocks, ctx.ports.s3Storage, ctx.ports.resend, ctx.ports.smtp, ctx.ports.meilisearch, and ctx.ports.openFeature are inferred from server/providers.ts.

Run your package manager install command after the preset writes dependency changes, then run beignet providers audit and beignet doctor --strict.

providers audit

beignet providers audit
beignet providers audit --json

Reports the provider packages installed by the target app without turning the report into a CI failure. The audit reads package-owned beignet.provider metadata without importing provider implementation modules, then shows metadata validity, registration status, required env, required tables, and declared app ports in the human table. JSON output also includes active variants and provider watchers.

Use the human table when checking an app manually. Use --json when a script, CI report, or coding agent needs a machine-readable provider inventory. Stable setup problems that should fail CI remain doctor diagnostics.

task run

beignet task run posts.backfill-search --tenant acme --input '{"dryRun":true}'

Runs an app-owned operational task through the registry in server/tasks.ts, which exports tasks, createTaskContext(...), and optionally stopTaskContext(...). Keep auth, tenancy, and provider lifecycle decisions in that module so local shells, CI jobs, and deployed runners behave the same.

schedule run

beignet schedule run posts.daily-summary --scheduled-at 2026-01-01T09:00:00.000Z

Runs a schedule explicitly from a local shell, CI job, or worker through the registry in server/schedules.ts, which exports a schedules array, createScheduleContext(...), and optionally stopScheduleContext(...). See Schedules.

outbox drain

beignet outbox drain --batch-size 100

Drains durable events and jobs in one bounded pass through the registry in server/outbox.ts, which exports outboxRegistry, createOutboxDrainContext(...), and optionally stopOutboxDrainContext(...). There is intentionally no separate jobs-drain command: outbox-backed jobs drain here, and direct provider jobs use provider-owned worker entrypoints such as an Inngest route. See Outbox.

outbox list

beignet outbox list --status deadLettered

Lists messages through ports.outboxAdmin from the app's outbox context. If the context does not expose outboxAdmin, the CLI accepts ports.outbox only when it also implements OutboxAdminPort, such as the memory outbox in tests.

outbox show

beignet outbox show <message-id>

Shows one outbox message, including payload, attempts, timestamps, and last error. Use --json for the full machine-readable record.

outbox requeue

beignet outbox requeue <message-id> --reset-attempts

Returns one dead-lettered message to pending state. Requeue only after the handler or provider issue has been fixed; Beignet preserves the last error for inspection.

outbox purge

beignet outbox purge --before 2026-01-01T00:00:00.000Z --dry-run
beignet outbox purge --before 2026-01-01T00:00:00.000Z

Deletes dead-lettered messages whose updatedAt is before the cutoff. The command requires either --before or --all.

outbox prune

beignet outbox prune --before 2026-01-01T00:00:00.000Z --dry-run
beignet outbox prune --before 2026-01-01T00:00:00.000Z

Deletes delivered messages whose deliveredAt is before the cutoff.

mcp

beignet mcp

Runs a Model Context Protocol server over stdio so coding agents can call the CLI as tools: routes, doctor, doctor_fix, lint, make, and provider_add. Tool outputs are the same JSON the matching --json flags print, make takes the same artifact kinds as beignet make, and provider_add takes { preset, dryRun? } for the same presets as beignet providers add. Generated apps ship a .mcp.json that runs ./node_modules/.bin/beignet mcp, so MCP clients such as Claude Code pick up the app-local CLI version without configuration. See Coding agents for the tool list, manual client registration, and the rest of the agent surface.

completion

beignet completion install
beignet completion install --shell zsh
beignet completion uninstall

install writes a managed completion block to ~/.bashrc or ~/.zshrc, detecting the shell from $SHELL; uninstall removes it. Restart your shell or source the rc file to activate. Completions cover commands, subcommands, flags, and enum values such as --with and --format, and complete whatever beignet resolves to on your PATH through the internal beignet completion propose helper.

Exit codes

Every command uses the same exit code contract, so CI scripts can branch on the result: