CLI

Schema lifecycle and operational commands

The jsorm binary handles initialization, SQL generation, health checks, and migration orchestration.

jsorm help

Initialization

Bootstrap a project with:

pnpm dlx @jsorm/core init
# or
npx -p @jsorm/core jsorm init

jsorm init now:

1. Detects whether src/schema/ exists — prompts for schema path only when missing.
2. Generates starter schema files (only if they don’t exist).
3. Loops database/adapters setup (you can add multiple databases). If a jsorm.config.ts already exists, existing connections are merged in.
4. Writes jsorm.config.ts.
5. Generates runtime helpers (db.ts by default, jsormdb.ts fallback when needed).
6. Verifies bootstrap and worker readiness before success output.

Use --no-migrations to skip migration scaffolding (no .migrations/, no migrations config).

Tip

The generated runtime helpers export create*Jsorm() and start*Jsorm() functions so apps can bootstrap explicitly.

Config-first mode

When jsorm.config.ts defines defaults, commands need no extra arguments:

jsorm db:check
jsorm migrate:status
jsorm migrate
jsorm migrate:up
jsorm migrate:down
jsorm table:create
jsorm table:create User
jsorm migrate:statement
jsorm migrate:statement initUsers
jsorm migrate:generate

Module-export mode (legacy fallback)

If not using config-first:

jsorm migrate ./dist/schema.js ormSource
jsorm migrate:up ./dist/schema.js ormSource
jsorm migrate:down ./dist/schema.js ormSource
jsorm migrate:status ./dist/schema.js ormSource
jsorm db:check ./dist/schema.js connectionSource
jsorm table:create ./dist/schema.js User
jsorm migrate:statement ./dist/schema.js initUsers
jsorm migrate:generate ./dist/schema.js generateSource

Compile first:

tsc && jsorm migrate:status ./dist/schema.js ormSource

Environment safety

Command	Safe in production	Notes
migrate	✅ Yes	Applies pending migrations only
migrate:up	✅ Yes	One step at a time
migrate:status	✅ Yes	Read-only
db:check	✅ Yes	Read-only
migrate:down	⚠️ Guarded	Requires JSORM_ALLOW_UNSAFE_OPERATIONS=true
db:fresh	❌ Blocked	Development only
db:rollback	❌ Blocked	Development only

Caution

db:fresh and db:rollback are blocked in production. Do not automate them in production pipelines.

migrate:generate

jsorm migrate:generate

Flow:

1. Read models from config.
2. Load .migrations/schema.json.
3. Build AST diff.
4. Classify changes (safe, review_required, dangerous).
5. Emit migration file.
6. Review before applying.

Engine and debug

If the engine is missing, CLI stops with explicit action hints:

[JSORM ENGINE MISSING] Run: pnpx jsorm init

Use explicit path in CI/container environments:

JSORM_ENGINE_PATH=/path/to/jsorm-engine jsorm migrate:status

Debug mode:

JSORM_DEBUG=1 jsorm migrate:status

Best practices

1. Use pnpm dlx @jsorm/core init for new projects.
2. Keep db:check in deploy verification.
3. Keep destructive commands out of production automation.
4. Run migrate:status during deployments.
5. Prefer explicit runtime startup (start*Jsorm() or createJsorm().init()) in app code.