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

1cd my-app2kalam dev

With environment overrides:

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

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

1kalam 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

Environment resolution

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

Configuring kalam dev

See kalam.toml Reference for the full field list. Key sections:

1[project]2package_manager = "pnpm"3 4[dev]5auto_start_db = true   # start or reuse local KalamDB (false for remote-only projects)6apply_schema = true    # run migration pipeline on startup and on schema changes7generate_types = true  # run kalam schema gen after schema apply8watch = true           # enable dev-side schema polling9 10# TypeScript init writes `app` automatically; add more keys as needed.11[dev.processes]12app = "pnpm dev"13agent = "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.

Package-manager dev commands written by init:

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 (default kalamdb123 for projects scaffolded with --server-mode local), or kalamdb123 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

Accessing the local server

While kalam dev is running, the managed server listens at your configured dev URL (default http://localhost:2900). Sign in with:

Admin UI — open http://localhost:2900/ui  and log in with root / kalamdb123.

CLI shell (another terminal, from any directory):

1kalam --url http://127.0.0.1:2900 --user root --password kalamdb123

Or save credentials once:

1kalam login --instance local --url http://127.0.0.1:2900 --user root --password kalamdb1232kalam --instance local

Health check:

1curl http://127.0.0.1:2900/v1/api/auth/status

These credentials come from auth.root_password in kalam/server/server.toml (default kalamdb123 for local init). Change the password there before the first kalam dev run if you need a different value.

Reset local database state

To wipe local project state and reset schema on the server:

1# Stop kalam dev first (Ctrl+C)2kalam db reset3kalam dev

If kalam dev reuses an existing server on localhost (no kalam/server directory in the project), the CLI prompts before dropping the namespace. Use kalam db reset --yes to confirm without prompting, or in CI/non-interactive shells.

See Migrations — kalam db reset for local vs server behavior and the confirmation rules.

App environment variables

Scaffolded .env / .env.example set workflow credentials for the CLI:

1KALAM_PROFILE=kalam-dev2KALAM_NAMESPACE=chat_app3KALAM_USER=root4KALAM_PASSWORD=kalamdb123

Browser and agent processes should use the KALAM_* / VITE_KALAM_* names:

Defaults match the local server: http://127.0.0.1:2900, user root, password kalamdb123.

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.

1# Point at a specific binary2export KALAMDB_SERVER_BIN="$HOME/.kalam/bin/kalamdb-server"3kalam 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: [cli] for workflow messages, [server] for the database, and [<process-key>] for each [dev.processes] entry (for example [app])
• 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:

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.

Note: The legacy kalam --watch-schema server-polling mode is deprecated. Use kalam dev with schema.sql instead.

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:

1export KALAMDB_SERVER_BIN="$HOME/.kalam/bin/kalamdb-server"2kalam 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:

1[dev.processes]2app = "pnpm 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:

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

Schema diff fails on second kalam dev with CREATE TOPIC

Use Kalam CLI v0.5.3-rc.1 or newer. Older CLI builds may apply the first migration but fail on the second dev run when diffing schemas that contain CREATE TOPIC. Update with kalam self-update or build from source.

Stale local data

When migrations or namespaces look wrong after many dev iterations, reset local project state:

1kalam db reset          # prompts if reusing a non-project server on localhost2kalam db reset --yes    # non-interactive / confirm namespace drop3kalam dev

Related commands

1kalam status              # project + migration summary2kalam schema gen          # regenerate types without dev session3kalam migration status    # applied / pending / failed migrations4kalam db migrate          # apply committed migrations explicitly5kalam db reset            # clear local kalam/server + optional namespace drop (see migrations doc)

Note: kalam deploy is not supported yet. Use kalam db migrate and your own rollout process for production.

Next

• kalam.toml Reference
• Migrations
• Project Init