Project Init
kalam init scaffolds a KalamDB project in the current directory (or --project-dir). It creates kalam.toml, a schema source, kalam/migrations/, generated-output paths, optional starter code from embedded templates, or a full example downloaded from the KalamDB repository. When TypeScript is selected, it runs your JavaScript package manager to install SDK dependencies.
Run this once per repository before kalam dev, kalam migration, or production rollout workflows.
For the full configuration reference, see kalam.toml Reference.
Quick start
While kalam dev runs, open http://localhost:2900/ui and sign in as root / kalamdb123, or use kalam --url http://127.0.0.1:2900 --user root --password kalamdb123 in another terminal.
For TypeScript projects, init detects npm, pnpm, yarn, or bun on PATH, prompts when more than one is installed, writes the choice to kalam.toml, and runs <manager> install after scaffolding.
Non-interactive bootstrap:
What kalam init creates
| Artifact | Purpose |
|---|---|
kalam.toml | Project config: environments, schema mode, codegen targets, dev orchestration, optional package_manager |
schema.sql | Active schema source when schema.mode = "sql" (from template or a starter stub) |
kalam/migrations/ | Migration history directory (default path; omitted from kalam.toml when unchanged) |
kalam/.schema-baseline.sql | Created on first successful schema apply during kalam dev |
kalam/.gitignore | Ignores local KalamDB state under kalam/ (server data, CLI logs, baselines) |
kalam/server/server.toml | Local server config when --server-mode local (includes auth.root_password) |
| Generated outputs | Paths from [schema.targets.<language>] (for example src/generated/kalam.ts) |
| Template or example files | Embedded TypeScript starter, or downloaded repository example when selected (default with --yes: simple-live) |
package.json + lockfile | TypeScript starter dependencies (when TypeScript is selected) |
.env / .env.example | Sets KALAM_PROFILE=kalam-dev, KALAM_USER=root, and KALAM_PASSWORD=kalamdb123 for local server mode |
kalam.toml stores URLs, namespaces, and toolchain choices only — no secrets. Authenticate with kalam login for remote servers, or let kalam dev bootstrap local root credentials on loopback.
Namespace naming
[connection.dev].namespace is derived from the project name using KalamDB identifier rules (for example chat-app → chat_app). If normalization changes the name, init prints the namespace it chose.
Init flags
| Flag | Description |
|---|---|
--name <NAME> | Project name (written to [project].name) |
--schema-mode <sql|remote> | Active schema source mode (remote is rejected until supported) |
--languages <typescript,dart> | Comma-separated codegen targets. Aliases: ts → typescript |
--template <id> | Embedded TypeScript template or repository example id (default simple-live with --yes) |
--package-manager <npm|pnpm|yarn|bun> | JavaScript package manager for TypeScript projects |
--server-mode <local|remote> | Whether kalam dev starts a local server or uses an existing URL |
--server-url <URL> | KalamDB URL for remote mode (local defaults to http://localhost:2900) |
--project-dir <PATH> | Directory to initialize (default: current directory) |
--yes | Skip prompts; use defaults for unspecified values |
Defaults with --yes
When a flag is omitted and --yes is set:
| Setting | Default |
|---|---|
| Schema mode | sql |
| Languages | typescript |
| Template | simple-live (TypeScript only) |
| Package manager | First available in order: invoking tool from npm_config_user_agent (when present), then pnpm, bun, yarn, npm |
| Server mode | local |
| Server URL | http://localhost:2900 |
| Project name | Current directory name, or my-app |
Interactive flow
When run in a TTY without --yes, kalam init walks through:
- Project name
- Schema mode — SQL file (
schema.sql) or remote (coming soon) - Language targets — multi-select TypeScript and/or Dart
- Project template — embedded starters plus repository examples such as
chat-with-ai,react-ai-chat, andsummarizer-agent - Package manager — when TypeScript is selected and multiple of npm/pnpm/yarn/bun are on
PATH - Server mode — local (
kalam devstarts or reuses a server) or remote - Server URL — when server mode is remote
Menus support Up/Down, Space (multi-select), Enter to confirm, and Esc to cancel.
In CI or piped shells without a TTY, pass --yes and every flag you need (including --package-manager when multiple managers are installed).
TypeScript package managers
TypeScript scaffolding lives under the CLI’s ts/ SDK module. Init only runs a package manager when typescript is in --languages (or selected interactively).
| Behavior | Detail |
|---|---|
| Detection | Scans PATH for npm, pnpm, yarn, and bun |
| Single manager installed | Selected automatically |
| Multiple installed | Interactive prompt; with --yes, uses preference order above |
| Explicit flag | --package-manager pnpm (or npm, yarn, bun) |
| Persistence | Written to [project].package_manager in kalam.toml |
| Install step | Runs <manager> install in the project root after files are created |
| Dart-only projects | No package manager field and no install step |
If dependency install fails, project files remain on disk. The CLI prints command output and recovery steps (for example cd <project> && pnpm install, then kalam dev).
Example kalam.toml
This matches the default TypeScript scaffold (local server, SQL schema). TypeScript init automatically writes [dev.processes].app with the selected package manager’s dev command. See kalam.toml Reference for every field.
Add more supervised processes with additional keys under [dev.processes] (for example worker = "cargo run --bin worker"). The log prefix always matches the key name.
Link an environment
After init, add or update named environments without re-running init:
kalam link updates [connection.<env>] in kalam.toml only. Login credentials stay in ~/.kalam/.
Schema commands (no database mutation for gen)
Inspect project state
Reports resolved URL, namespace, schema mode, codegen targets, and migration counts.
Starters And Examples
TypeScript projects can start from embedded samples or repository examples.
Embedded samples live under cli/templates/typescript/* and are compiled into the CLI:
simple-live is a live-subscription starter with sample schema.sql, src/index.ts, and SDK dependencies. Init scaffolds [dev.processes].app so kalam dev can supervise the starter automatically. List available samples interactively during kalam init, or pass --template with --yes.
Repository examples live under examples/. They appear in the same kalam init template menu even when you installed only the CLI. When selected, the CLI downloads the repository archive and copies the chosen example into your project directory:
Available repository example ids include live-okf-context-sync, realtime-ops-feed, chat-with-ai, react-ai-chat, and summarizer-agent.
Troubleshooting
interactive setup needs a terminal (TTY)
Run in a regular terminal, or pass non-interactive flags:
No JavaScript package manager on PATH
Install Node.js (includes npm), pnpm , or bun , open a new terminal, then rerun init. For TypeScript with --yes, add --package-manager <name> once a manager is available.
Explicit package manager not found
If you pass --package-manager npm but only pnpm is installed, either install npm or choose an installed manager:
Dependency install failed after scaffolding
Project files are already created. Finish manually:
The CLI surfaces network, permission, Node version, and registry errors when it can infer them from the package manager output.
Project already exists
If kalam.toml is already present in the directory, init refuses to overwrite. Use a different --project-dir, or open the existing project and run kalam dev.
Next steps
- Local Development — run
kalam dev - kalam.toml Reference — full config field reference
- Migrations — draft, seal, and apply schema history