Skip to Content
Local Development

Local Development

kalam dev is the canonical local orchestration entry point for KalamDB projects. It reads kalam.toml, prepares the development database, runs the schema pipeline, regenerates language artifacts, watches schema.sql for changes, and supervises configured child processes.

Quick start

BASH
cd my-appkalam dev

With environment overrides:

BASH
kalam dev --env dev --namespace app --project-dir .

Retry a paused schema pipeline on startup (skips draft confirmation prompts):

BASH
kalam dev --force

What kalam dev does

On startup, in order:

  1. Resolve environment — URL, namespace, and env name from flags, environment variables, then kalam.toml
  2. Prechecks — schema source exists, codegen target dirs, migrations dir, kalam/.gitignore, CLI log dir, server reachability or binary availability
  3. Authentication (early) — for remote servers (auto_start_db = false) or when a local server is already running at the configured URL; verifies saved credentials or prompts you to run kalam login
  4. Local server — when [dev].auto_start_db = true and nothing is listening yet, download (interactive) / locate kalamdb-server, spawn it, wait for health, then log in as local root and save credentials to ~/.kalam/ for profile kalam-<env> (for example kalam-dev)
  5. Schema pipeline — diff schema.sql, update _draft.sql, apply numbered migrations, regenerate types when configured
  6. Draft prompt — if _draft.sql remains and you did not pass --force, show Apply / Reset / Cancel
  7. Child processes — start commands from [dev.processes] when configured
  8. File watch loop — poll the schema source every 2 seconds when both [dev].watch and [schema].watch are true

Press Ctrl+C to shut down managed processes cleanly.

If you have no [dev.processes], no local server was spawned, and file watch is disabled, the session may exit after the schema pipeline completes.

Dev flags

FlagDescription
--project-dir <PATH>Project root containing kalam.toml
--env <NAME>Environment to use (default from [project].default_env)
--namespace <NAME>Override namespace for this session
--forceSkip draft confirmation prompts; use forceful migration apply options; retry a failed schema pipeline once on startup
--progressDeprecated — ignored; kalam dev always uses append-only multiplexed logs

Environment resolution

SettingResolution order (first match wins)
Environment name--env → KALAM_ENV → [project].default_env → dev
Server URLKALAM_URL → [connection.<env>].url
Namespace--namespace → KALAM_NAMESPACE → [connection.<env>].namespace

Credential profile for workflow auth comes from .env (KALAM_PROFILE, default kalam-dev) or kalam login --instance kalam-<env>.

Configuring kalam dev

TOML
[project]package_manager = "pnpm" [dev]auto_start_db = true   # start or reuse local KalamDB (false for remote-only projects)apply_schema = true    # run migration pipeline on startup and on schema changesgenerate_types = true  # run kalam schema gen after schema applywatch = true           # enable dev-side schema polling # Optional — omit when you only need DB + schema tooling[dev.processes]frontend = "pnpm run dev"agent = "dart run bin/agent.dart"

Both [schema].watch and [dev].watch must be true for file watching. If either is false, kalam dev does not poll the schema file.

Match [dev.processes] commands to [project].package_manager from kalam init (for example pnpm run dev when package_manager = "pnpm"). Default kalam init does not add [dev.processes] — add it when you want the CLI to supervise your app.

Local KalamDB server

When [dev].auto_start_db = true (the default for --server-mode local during init):

  1. Health check — if the configured URL already responds, reuse that server (auth is verified during prechecks)
  2. Start binary — otherwise spawn kalamdb-server with config at kalam/server/server.toml
  3. Bootstrap auth — log in as root using auth.root_password from kalam/server/server.toml, or mypass on loopback when no password is configured, then save JWT credentials for kalam-<env>
  4. Data & logs — server storage under kalam/server/data and kalam/server/logs

Finding kalamdb-server

The CLI resolves the server binary in this order:

  1. KALAMDB_SERVER_BIN — absolute path to the binary (use kalamdb-server.exe on Windows)
  2. Binary colocated next to the kalam executable
  3. ~/.kalam/bin/kalamdb-server (managed install directory)
  4. kalamdb-server on PATH

On first kalam dev in an interactive terminal, the CLI can download the matching server release into ~/.kalam/bin when no binary is found. Non-interactive environments (CI) must preinstall the server or set KALAMDB_SERVER_BIN.

BASH
# Point at a specific binaryexport KALAMDB_SERVER_BIN="$HOME/.kalam/bin/kalamdb-server"kalam dev

See Server binaries for manual downloads.

Managed service logs

kalam dev multiplexes logs from the local server and every [dev.processes] entry into one append-only console stream:

  • Each line is prefixed with a stable source label (server, frontend, agent, …)
  • Sources use distinct colors when the terminal supports it
  • When [logging].file = true, the same lines are mirrored to kalam/cli/logs/kalam.log (secrets redacted)

If schema apply fails, the failure is shown prominently and only the schema pipeline pauses. Server and frontend logs keep streaming so you can debug without losing context.

Schema pipeline during dev

When apply_schema is enabled and schema.mode = "sql":

  1. Diff schema.sql against kalam/.schema-baseline.sql (when no numbered migrations are pending)
  2. Write or update kalam/migrations/_draft.sql when changes exist
  3. Apply numbered migrations that are not yet on the server (--force uses forceful apply options)
  4. Update the baseline after a successful apply unless a draft is still pending confirmation
  5. Run kalam schema gen when generate_types = true

With --force, numbered migrations still apply immediately, but _draft.sql is not auto-sealed — you still confirm draft application unless you seal/apply through migration commands.

See Migrations for draft sealing, kalam db migrate, and recovery commands.

Draft migration prompt

When _draft.sql exists and you did not pass --force, kalam dev pauses streaming output and shows a modal selector:

ChoiceBehavior
Apply changesSeal and apply the draft migration, then refresh baseline/types
Reset and rebuildDrop the namespace on the server, clear local numbered migrations + baseline, rebuild from schema.sql
CancelStop kalam dev without applying

In non-interactive terminals, send y (apply), r (reset), or any other key (cancel).

File watch behavior

When watch is enabled, kalam dev polls the schema file every 2 seconds. On change:

  1. Debounce — wait until the file metadata stabilizes (editors often save in bursts; up to ~2s)
  2. Diff — update _draft.sql from the new schema vs baseline when no numbered migrations are pending
  3. Apply — run the schema pipeline (numbered migrations first; draft stays pending until you confirm)
  4. Regenerate — refresh TypeScript/Dart outputs when configured
  5. Prompt — show the draft modal again when _draft.sql remains (unless --force)

This is file-based watch — it reacts to edits on schema.sql in your repo. It does not poll system.tables on the server.

For server-side DDL watch (any client changing the database), use Remote Schema Watch (kalam --watch-schema).

Local vs remote server mode

Set during kalam init or in kalam.toml:

  • Local (--server-mode local, [dev].auto_start_db = true) — kalam dev may download, spawn, or reuse kalamdb-server
  • Remote (--server-mode remote, [dev].auto_start_db = false) — kalam dev connects to [connection.<env>].url and never starts a local binary

Troubleshooting

kalamdb-server was not found

Install or download the server, or set an explicit path:

BASH
export KALAMDB_SERVER_BIN="$HOME/.kalam/bin/kalamdb-server"kalam dev

In CI, preinstall the binary before running kalam dev. Interactive download requires a TTY.

KALAMDB_SERVER_BIN points to a file that does not exist

Unset the variable to let the CLI auto-locate the server, or fix the path (include .exe on Windows).

Dev process failed to start ([dev.processes])

The CLI prints the shell command and actionable hints:

  • Verify the program exists on PATH (or use an absolute path in kalam.toml)
  • Run the command manually from the project root
  • On Windows, npm/pnpm/yarn are often *.cmd shims — kalam dev runs process commands through the system shell (cmd /C)

Example fix when pnpm is recorded in kalam.toml:

TOML
[dev.processes]frontend = "pnpm run dev"

Schema pipeline paused

A migration or codegen step failed. Child processes and the local server may keep running while schema work is paused. Retry once at startup:

BASH
kalam dev --force

Check [server] and schema log lines, then fix schema.sql or migration files before rerunning.

Authentication / login errors

For remote servers, run kalam login --instance kalam-<env> and ensure .env sets KALAM_PROFILE to that profile.

For local servers, kalam dev tries saved credentials first, then root login using kalam/server/server.toml. If that fails, run kalam login or fix auth.root_password in the server config. See Authentication.

BASH
kalam status              # project + migration summarykalam schema gen          # regenerate types without dev sessionkalam migration status    # applied / pending / failed migrationskalam db migrate          # apply committed migrations explicitlykalam deploy --env prod   # production rollout (no auto-draft)

Next

Last updated on
Project InitMigrations