Init and Dev Workflow

Two commands get a local KalamDB app running: kalam init scaffolds the project, then kalam dev starts the database, applies schema.sql, and supervises your app.

1mkdir my-app && cd my-app2kalam init3kalam dev

Non-interactive equivalent:

1kalam init --yes \2  --name my-app \3  --languages typescript \4  --template simple-live \5  --package-manager pnpm \6  --server-mode local7kalam dev

While kalam dev is running, open http://localhost:2900/ui  and sign in as root / kalamdb123.

What kalam init writes

kalam.toml stores URLs and toolchain choices only — no secrets. Local root credentials live in kalam/server/server.toml and .env.

What kalam dev does

1. Resolves the URL and namespace from kalam.toml (default http://localhost:2900)
2. Starts kalamdb-server when nothing is listening, or warns and reuses whatever is already on that URL
3. Logs in as local root and saves credentials under ~/.kalam/
4. Diffs schema.sql, applies migrations, and regenerates SDK types
5. Injects the project .env into [dev.processes] (for example pnpm dev) so KALAM_PASSWORD reaches Node even if the app does not load dotenv itself
6. Watches schema.sql and multiplexes [cli], [server], and [app] logs

Press Ctrl+C to shut down processes that this session started.

Port already in use

If another kalamdb-server or cargo run is already bound to port 2900, kalam dev reuses it instead of starting kalam/server for this project. The warning is explicit: that listener may not be this project’s managed server.

Stop the other process if you expected a fresh local instance, or scaffold against a free port:

1kalam init --yes --name my-app --languages typescript --server-mode local --server-url http://localhost:2933

App credentials

kalam init writes KALAM_PASSWORD=kalamdb123 into .env. kalam dev injects those values into child processes when they are not already set in the parent environment. New TypeScript starters also import 'dotenv/config' so npm run dev outside kalam dev still sees the password.

If the app logs KALAM_PASSWORD is required, confirm .env exists in the project root and that you rebuilt a CLI that injects it.

Next

• Project Init — flags, templates, and kalam.toml shape
• Local Development — prechecks, watch, draft prompt, and troubleshooting
• Getting started — Docker, CLI, and binary install paths