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, and Pino 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.

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. 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.

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 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 event and make job append the feature's registries to defineOutboxRegistry({...}) in server/outbox.ts when that file already exists; the outbox registry is opt-in, so the generators never create it. See Outbox.
• make event and make resource --events wire eventBus: EventBusPort into AppPorts, register createInMemoryEventBusProvider() 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; run seeds from the app-owned infra/db/seed.ts entrypoint with runSeeds(...). See Database.

db

beignet db generate
beignet db migrate
beignet db seed
beignet db reset

Each subcommand delegates to the app-owned package script of the same name (db:generate, db:migrate, db:seed, db:reset) and checks 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.

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 server/outbox.ts exists, listeners that no registerListeners(...) call references, 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, unwired repository adapters, 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, credentialed wildcard CORS, uploads without routes or size limits, and notification dispatchers that bypass ctx.ports.notifications.
• Payments — billing slices without a payment webhook route, 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).

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

task run

beignet task run posts.backfill-search --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.

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, and make. Tool outputs are the same JSON the matching --json flags print, and make takes the same artifact kinds as beignet make. Generated apps ship a .mcp.json that registers the server, so MCP clients such as Claude Code pick it up 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: