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 built-in templates, and—when TypeScript is selected—runs your JavaScript package manager to install SDK dependencies.
Run this once per repository before kalam dev, kalam migration, or kalam deploy.
Quick start
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 files | TypeScript starter 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 so workflow commands resolve saved CLI credentials |
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> | Built-in TypeScript template (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
- Template source & template — built-in TypeScript templates (
simple-livetoday; repository templates are listed but not available yet) - 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 scaffold (local server, TypeScript, SQL schema). [migrations].dir defaults to kalam/migrations and is usually omitted from the file.
Add child processes when you want kalam dev to supervise an app server alongside KalamDB:
Use the same package manager in [dev.processes] that you recorded in [project].package_manager (for example pnpm run dev vs npm run dev). The simple-live template ships package.json scripts but does not add [dev.processes] automatically — configure it when you want the CLI to start your frontend.
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.
Built-in templates
TypeScript projects can start from embedded templates:
simple-live is a live-subscription starter with sample schema.sql, src/index.ts, and SDK dependencies. Run it manually with your package manager (pnpm run dev, npm run dev, …) or add a [dev.processes] entry so kalam dev supervises it. List available templates interactively during kalam init, or pass --template with --yes.
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 - Migrations — draft, seal, and apply schema history
- Schema Watch — file watch vs remote polling