CLI Reference

Seed the config from a preset (non-interactive). minimal: auth off, one example entity — the smallest runnable API. api: consumer-mode (resource server) + authorization + rate-limit + monitoring. saas: full auth (login/register/email-verify) + multi-tenant + email + storage/CDN + notifications + monitoring + audit + rate-limit. marketplace: the SaaS stack plus Stripe payments and the marketplace money layer (splits/reserves/payouts).

Scaffold around an existing config.json instead of building one — the file is used as-is (after validation) and its appId is honoured.

The app id for the new project. Slugified. When omitted it is prompted for (interactive) or defaults to my-app (with --yes/--preset).

Target directory. Defaults to ./<appId>. A non-empty existing directory is confirmed (and aborted if you decline) only in interactive mode; in non-interactive mode (--yes/--preset/--config) init prints a warning and writes into it anyway — so point -o at a fresh dir in CI to avoid clobbering.

No prompts. Implies the saas preset unless --preset or --config is given. Ideal for CI and scripted scaffolds.

Write the files but skip `bun install` and the schema generation step. Useful when you only want the source, or in an offline sandbox — run `bun install && bun run generate` yourself afterwards.

Probes Postgres and Redis at their configured host:port. Anything already reachable is left untouched — so your existing local Postgres/Redis are used as-is. For a missing datastore on a local host it starts a throwaway Docker container (nucleus-dev-postgres on postgres:16-alpine, nucleus-dev-redis on redis:7-alpine), reusing a stopped one if present, and waits until it accepts connections. A missing datastore on a remote host is reported, not started.

Warns if Postgres/Redis are not reachable, then runs the project's `dev` script (or `bun --watch src/index.ts` if there is none), streaming its output until Ctrl-C. The scaffolded backend listens on port 4000 with Swagger at /docs. Invokable as bare `nucleus dev` or, identically, as the explicit `nucleus dev run` — so the three subcommands are up | down | run (any other sub errors).

Removes the nucleus-dev-postgres and nucleus-dev-redis containers if they exist. It never touches datastores it did not start (a container it did not create is out of scope).

Column-by-column entity builder (table name, columns with types, NOT NULL, public GET, bulk endpoints). Appends to config.entities (skipping any name that already exists), then runs `generate` to rewrite src/drizzle/schema.ts + relations.ts. (Alias: `add entities`.)

Enables a feature block with schema-valid defaults. storage turns on local storage + CDN; payment prompts for iyzico or Stripe. No schema regeneration is needed (features don't change tables). Already-enabled features are left as-is.

Adds an OAuth provider under authentication.oauth with CLIENT_ID / CLIENT_SECRET env-var placeholders. Requires authentication to be enabled (the api and saas presets have it on).

Validates the config against the generated JSON-Schema, then applies cross-field rules the schema can't express (appId and database.url are required; entities present; authentication.mode is required when authentication is enabled, and consumer mode combined with authorization requires authentication.idpUrl for /auth/check; payment.provider matches its block; notification channels have their credentials; chat attachments require storage + CDN). Missing 'required' schema fields that have runtime defaults surface as warnings, not errors — as do unknown or misspelled config keys not present in the schema (when additionalProperties is false), so typos surface non-blockingly. Also prints every env var the config references. Exit 1 on any error. (Alias: check.) Note: doctor runs the same schema check but reports only errors, not these warnings.

Green/red checklist: bun runtime; Postgres reachable (DATABASE_URL); Redis reachable (REDIS_URL / REDIS_HOST+REDIS_PORT); docker, dapr and createdb as optional tooling; and — if a config is present — its validity plus any referenced env vars that are unset. Exit 1 if a required check (bun / Postgres / Redis / a valid config) fails.

Reads your config.json and writes the Drizzle schema.ts + relations.ts the plugin loads, merging your entities with the built-in system tables (users, user_sessions, roles, claims, audit_logs, …). Run it after every entity change — `add entity` does this for you. A leading path argument is auto-detected, so `nucleus src/config.json src/drizzle` also works. (Alias: gen.)

Interactive scaffolding of a complete starting point — the Elysia API, a frontend, Kubernetes manifests and CI/CD pipelines — so a new service is deployable from day one. This is the heavier sibling of init, which produces just a lean, runnable backend. (Alias: new.)