Docs / Build an application

CLI OverviewSupported

@zmdb/cli owns the single installed zmdb executable. Its commands delegate reflection and AOT compilation to @zmdb/compiler, and schema snapshots, plans, files and ledger execution to @zmdb/migrations. These libraries are independently usable; see Tooling Boundaries.

The pieces#

Function	Module	Does
`compileProject`, `writeCompileResult`, `watchCodegen`	`@zmdb/compiler`	project artifacts, freshness checks and retained-session watch
`snapshot(schemas)`	`@zmdb/migrations`	schema objects → a plain snapshot object
`diff(prev, next)`	`@zmdb/migrations`	two snapshots → operations
`emitUp(op, dialect)`	`@zmdb/migrations`	one operation → SQL
`emitDown(op, dialect)`	`@zmdb/migrations`	the reverse
`sqliteIntrospector`	`@zmdb/sqlite`	SQLite catalog → normalized snapshot
`database.introspector`	selected database package	database-owned catalog reader
`emitDeclarations(snapshot, …)`	`@zmdb/migrations/declarations`	snapshot → generated TypeScript files
`up`, `down`, `status`	`@zmdb/migrations/runner`	applies / reverts, records versions
`runEmbedded(conn, migrations)`	`@zmdb/migrations/embedded`	applies bundle-resident SQLite migrations

The commands, and where each stands#

drizzle-kit / mikro-orm	zmdb today	Page
`new`	project and application-component scaffolds	scaffolding
`codegen`	`zmdb codegen`, `--check` and `--watch`	code generation
`generate`	`zmdb generate`	generate
`embed`	bundle-resident SQLite migration module	web/mobile migrations
`migrate` / `up`	`zmdb migrate`; `up` is deliberately refused	migrate · up
`push`	live-catalog diff with a destructive SQL guard	push
`check`	snapshot, file-history, and optional live-drift checks	check
`export`	`zmdb export`	export
`pull` / `generate-entities`	protected `zmdb pull` declaration staging	pull
`client generate`	OpenAPI and typed client from configured HTTP contracts	generated client
`studio`	installed read-only loopback browser	studio

The catalog-backed pull is packaged with overwrite protection, dry-run, and check modes. Studio's installed binary is parsed by plain Node and exercised against its loopback index by publish verification.

A single entry point#

Install the CLI and its required TypeScript peer, or install @zmdb/core@1.0.0-beta.2 for the product that includes the same CLI. Command help comes from the installed version:

yarn add --dev @zmdb/cli@1.0.0-beta.2 typescript@^7.0.2
yarn zmdb --help
yarn zmdb codegen --help

The database workflow uses that one entry point:

yarn zmdb codegen --check
yarn zmdb generate --name add_slug
yarn zmdb embed
yarn zmdb migrate
yarn zmdb check --json
yarn zmdb export > schema.sql
yarn zmdb pull --dry-run
yarn zmdb client generate --check
yarn zmdb new controller posts

The schema and HTTP-generation commands accept --config <path> and --project <tsconfig>. client generate writes both configured artifacts, --check reports stale output without writing, and --watch regenerates from the compiled contract dependency set. Scaffolding instead accepts --package <name-or-path> and --dry-run and does not load database config. Add --json when a script needs the stable CliResult envelope instead of human output; watch mode is deliberately not JSON.

Exit codes and streams#

Exit	Meaning
`0`	The command completed and found no requested check failure.
`1`	Work ran, but an operation failed or a check found drift.
`2`	The invocation, config, safety confirmation, or command name was invalid.

Human progress goes to stdout. Under --json, stdout is one CliResult document and progress or warnings move to stderr, so a caller can parse stdout without filtering log lines.

---

See also: Generated HTTP Client · Migrations · Config File · generate

← Previous

Tooling: compiler, migrations and CLI

Config File