`kalam.toml` Reference

kalam.toml is the project configuration file at the repository root. Workflow commands (kalam init, kalam dev, kalam migration, kalam schema, kalam db, kalam status, kalam link) read it to resolve environments, schema sources, codegen targets, and dev orchestration.

Secrets do not belong in kalam.toml. URLs and namespaces are fine; passwords and JWTs stay in ~/.kalam/ (credential profiles like kalam-dev).

Project layout

TEXT

1my-app/2├── kalam.toml3├── schema.sql4├── .env / .env.example5├── kalam/6│   ├── migrations/7│   ├── .schema-baseline.sql8│   ├── .gitignore9│   ├── cli/logs/kalam.log10│   └── server/11│       ├── server.toml12│       ├── data/13│       └── logs/14├── src/generated/kalam.ts    # TypeScript15└── lib/generated/kalam.dart  # Dart

The default project data directory is kalam/ (override with [project].kalam_dir).

Full example

TOML

1[project]2name = "my-app"3default_env = "dev"4package_manager = "pnpm"5 6[connection.dev]7url = "http://localhost:2900"8namespace = "my_app"9 10[connection.prod]11url = "https://db.example.com"12namespace = "my_app"13 14[schema]15mode = "sql"16path = "schema.sql"17watch = true18languages = ["typescript", "dart"]19 20[schema.targets.typescript]21output = "src/generated/kalam.ts"22 23[schema.targets.dart]24output = "lib/generated/kalam.dart"25 26[migrations]27auto_create = true28 29[dev]30auto_start_db = true31apply_schema = true32generate_types = true33watch = true34 35[dev.processes]36app = "pnpm dev"37worker = "cargo run --bin worker"38 39[logging]40file = true41capture_process_output = true

`[project]`

Field	Required	Default	Description
`name`	yes	—	Project name
`default_env`	no	`dev`	Default environment for workflow commands
`package_manager`	no	—	`npm`, `pnpm`, `yarn`, or `bun` — written by `kalam init` for TypeScript projects
`kalam_dir`	no	`kalam`	Relative path for migrations, local server config, CLI logs, and schema baselines

`[connection.<env>]`

Field	Required	Description
`url`	yes	KalamDB HTTP URL
`namespace`	yes	Namespace identifier

Add or update environments without re-running init:

BASH

1kalam link --env staging --url https://staging.example.com --namespace my_app

`[schema]`

Field	Required	Default	Description
`mode`	yes	—	`sql` (local file) or `remote`
`path`	when `mode = "sql"`	—	Schema source path (typically `schema.sql`)
`watch`	no	`true`	Enable file watch together with `[dev].watch`
`languages`	no	`["typescript"]`	Codegen targets: `typescript`, `dart`

Each language in languages requires a matching [schema.targets.<language>] block.

`[schema.targets.<language>]`

Field	Required	Description
`output`	yes	Path for generated SDK/schema artifacts (must be unique per language)

`[migrations]`

Field	Default	Description
`auto_create`	`true`	Automatically maintain `kalam/migrations/_draft.sql` from schema diffs
`dir`	`kalam/migrations`	Migration directory (default; usually omitted from the written file)

`[dev]`

Field	Default	Description
`auto_start_db`	`true`	Start or reuse a local `kalamdb-server` (`false` for remote-only)
`apply_schema`	`true`	Run the migration pipeline on startup and on schema file changes
`generate_types`	`true`	Run `kalam schema gen` after schema apply
`watch`	`true`	Poll the schema file during `kalam dev` (requires `[schema].watch = true`)

`[dev.processes]`

Optional map of process name → shell command. kalam dev supervises each entry alongside the database server and schema pipeline.

Behavior	Detail
Init default	TypeScript projects get `app = "<manager> dev"` automatically (`npm run dev`, `pnpm dev`, `yarn dev`, or `bun run dev`)
Log prefix	Each key becomes a stable prefix — `[app]`, `[worker]`, etc. — distinct from `[cli]` workflow output and `[server]` database logs
Execution	Commands run from the project root through the system shell
Multiple processes	Add any number of entries
Dart-only projects	Section is omitted; scaffold includes a commented example

TOML

1[dev.processes]2app = "pnpm dev"3agent = "dart run bin/agent.dart"

`[logging]`

Field	Default	Description
`file`	`true`	Write workflow logs to disk
`capture_process_output`	`true`	Mirror managed process stdout/stderr into the log file (secrets redacted)
`path`	`kalam/cli/logs/kalam.log`	Log file path (default; usually omitted from the written file)

Environment resolution

Setting	Resolution order (first match wins)
Environment name	`--env` → `KALAM_ENV` → `[project].default_env` → `dev`
Server URL	`KALAM_URL` → `[connection.<env>].url`
Namespace	`--namespace` → `KALAM_NAMESPACE` → `[connection.<env>].namespace`

Credential profiles follow the pattern kalam-<env> in ~/.kalam/. After kalam init, .env sets KALAM_PROFILE=kalam-dev.

Validation

The CLI validates kalam.toml on load:

project.name must be non-empty
project.kalam_dir must be a relative in-project path
schema.path is required when schema.mode = "sql"
Every schema.languages entry needs a matching [schema.targets.<lang>]
Generated output paths must be unique
package_manager must be one of npm, pnpm, yarn, bun when set

Project Init — scaffolding and flags
Local Development — orchestration and log multiplexing
Migrations — draft, seal, and apply

kalam.toml Reference

Project layout

Full example

[project]

[connection.<env>]

[schema]

[schema.targets.<language>]

[migrations]

[dev]

[dev.processes]

[logging]