Kalam CLI Command Reference

The Kalam CLI (kalam) is the SQL-first terminal client for KalamDB. It is available as the native Rust binary and as the npm-distributed wrapper package @kalamdb/cli. This guide documents the current operational surface: install paths, self-update, doctor diagnostics, login/logout, instance profiles, live subscriptions, topic consumers, and schema watch automation.

Install and verify

Choose one of these installation options:

Option 1: npm global install

1npm install -g @kalamdb/cli

Use this when your machine already manages developer tools through Node/npm. The package downloads the matching native release binary during install.

Option 2: install.sh

1curl -fsSL https://kalamdb.org/install.sh | sh

Use this when you want a curl-based install path and do not want to involve npm.

Pin an exact release by passing installer flags through sh -s --:

1curl -fsSL https://kalamdb.org/install.sh | sh -s -- --version 0.5.1-beta.2

Install the latest GitHub prerelease:

1curl -fsSL https://kalamdb.org/install.sh | sh -s -- --pre-release

The installer also accepts environment variables, which are often easier in CI:

1curl -fsSL https://kalamdb.org/install.sh | KALAM_VERSION=0.5.1-beta.2 sh2curl -fsSL https://kalamdb.org/install.sh | KALAM_PRE_RELEASE=1 sh3curl -fsSL https://kalamdb.org/install.sh | KALAM_INSTALL_DIR=/usr/local/bin sh4curl -fsSL https://kalamdb.org/install.sh | KALAM_NO_MODIFY_PATH=1 sh

Supported installer inputs:

Option 3: GitHub release binaries

Use prebuilt binaries from releases if you do not want a Rust toolchain:

• /docs/server/getting-started/binaries

Option 4: Build from source

1cd cli2cargo build --release3./target/release/kalam --help

After installation, verify your CLI:

1kalam --help2kalam version3kalam doctor

kalam version prints the packaged version plus build metadata such as commit, branch, and build timestamp. kalam doctor gives you a compact status summary by default and a fuller, Flutter-style detail view when you pass -v.

KalamDB Skills for coding agents

Use KalamDB Skills alongside the CLI so Codex, Claude Code, OpenCode, and Agent Skills-compatible tools can load KalamDB commands, SQL syntax, SDK patterns, and operations guidance:

1npx skills add kalamdb/kalamdb-skills

Release, auth, and instance workflows

Top-level commands are the preferred operational surface for daily CLI management:

1kalam version2kalam doctor3kalam doctor -v4kalam update5kalam login --instance prod --url https://db.example.com --user root --password6kalam login --instance prod --url https://db.example.com --oidc7kalam login --instance prod --url https://db.example.com --oidc --no-browser8kalam whoami --instance prod9kalam logout --instance prod10kalam token create --name ci-prod --instance prod

What these commands do:

• kalam update downloads a verified release archive, shows a progress bar while the binary is downloading, verifies SHA256SUMS, and replaces the installed native binary.
• kalam doctor checks the binary path, PATH resolution, config file, stored credentials, healthcheck reachability, and authenticated identity.
• kalam login saves access and refresh tokens for the selected --instance unless you pass --no-save.
• kalam whoami calls /v1/api/auth/me with the resolved credentials.
• kalam logout deletes saved credentials for one instance or, with --all, every stored instance.
• kalam token create creates a service user and prints a fresh access/refresh token pair for automation.

When interactive mode starts, the CLI performs a short update check. If a newer release is available, it prints a one-time notice and adds an update:<version> segment to the prompt so the operator can see that the shell is behind the latest release.

Execution modes and precedence

kalam supports four execution modes:

1. --watch-schema: poll system.tables and run a local command when schema metadata changes.
2. --subscribe / --list-subscriptions: subscription management flow.
3. --consume --topic ...: topic consumer mode.
4. SQL execution mode:
   • --file <path> executes file and exits
   • --command <sql> executes one statement and exits
   • no --file/--command starts interactive shell

Important behavior:

• --watch-schema is a standalone mode and requires --run.
• --consume takes precedence over --file and --command.
• --file and --command together are invalid.

Connection and authentication options

URL defaults and resolution:

• If --url is set, that value is normalized and used. Bare hosts are accepted.
• If --host is set, URL becomes http://<host>:<port>.
• Otherwise CLI uses stored credentials URL for the selected --instance when present.
• Final fallback is http://localhost:2900.
• Bare --url inputs like localhost:2900, 127.0.0.1:2900, and [::1]:2900 default to http://...; other bare hosts like kalam.masky.app default to https://....
• --url rejects embedded credentials, query parameters, and fragments.

For production-style workflows, use named instances so one CLI install can keep separate URLs and credentials for dev, staging, and prod.

Example:

1kalam login --instance dev --url http://127.0.0.1:2900 --user admin --password2kalam login --instance staging --url https://staging-db.example.com --user admin --password3kalam login --instance prod --url https://db.example.com --user admin --password4 5kalam whoami --instance prod

OIDC login modes

KalamDB now exposes one configured external OIDC provider. The CLI supports three ways to use it:

Browser login with PKCE

1kalam login --instance prod --url https://db.example.com --oidc

This opens the provider login page in your browser, listens for the local callback on http://127.0.0.1:8787/callback, and exchanges the authorization code through KalamDB.

Direct device login

1kalam login --instance prod --url https://db.example.com --oidc --no-browser

Use this when the provider exposes a device authorization endpoint and you do not want a local browser callback.

Brokered device login

1kalam login --instance prod --url https://db.example.com --oidc --no-browser --brokered

Use brokered mode when the CLI host can reach KalamDB but cannot reach the OIDC provider directly.

Operational notes:

• --brokered requires --no-browser
• kalam login --no-save ... skips writing credentials to disk
• when kalam login succeeds in an interactive terminal, the CLI drops straight into the SQL shell
• when stdin or stdout is non-interactive, kalam login keeps one-shot behavior and exits after saving credentials

Query execution and output options

Examples:

1kalam --command "SELECT * FROM system.tables LIMIT 5;"2kalam --command "SELECT * FROM system.tables LIMIT 5;" --json3kalam --file ./setup.sql --csv4kalam --url kalam.masky.app --command "SELECT 1;"

Running SQL from the CLI

The CLI is SQL-first: if a statement works through /v1/api/sql, you can send it unchanged through kalam --command, kalam --file, or the interactive shell.

Common patterns:

1# Read system metadata2kalam -c "SELECT * FROM system.tables ORDER BY namespace_id, table_name LIMIT 20;"3 4# DDL / DML5kalam -c "CREATE NAMESPACE chat;"6kalam -c "CREATE TABLE chat.messages (id BIGINT PRIMARY KEY, body TEXT) WITH (TYPE='USER');"7kalam -c "INSERT INTO chat.messages (id, body) VALUES (1, 'hello');"8 9# Run a whole SQL file10kalam -f ./migrations/001-init.sql

Namespace state in interactive mode

Namespace switching is a SQL statement, not a backslash command:

1USE NAMESPACE chat;2SELECT * FROM messages ORDER BY id DESC LIMIT 20;3\flush table messages

After a successful USE NAMESPACE chat, SET NAMESPACE chat, or USE chat, the CLI stores chat locally and sends it as namespace_id on later requests. That means later unqualified table names resolve to chat.<table> until you switch again. The prompt also shows the active namespace as ns:<name>.

Table footer metadata

When output format is table, query results end with row count and footer metadata:

1(50 rows)23As: alice4Took: 2.146 ms

• As: appears when the server reports the effective user for the statement. This includes EXECUTE AS '<user_id>' and the CLI \as shortcut.
• Took: is the server-reported execution time in milliseconds.

Interactive meta-commands

In interactive mode, type SQL directly or use backslash meta-commands for CLI-managed operations. --command also accepts these meta-commands, so cluster inspection and administration can stay on the CLI surface instead of requiring backend-rendered strings.

Cluster meta-commands

Core cluster commands:

Examples:

1kalam --command "\\cluster list"2kalam --command "\\cluster list groups"3kalam --command "\\cluster rebalance"4kalam --command "\\cluster join 2 10.0.0.2:2910 http://10.0.0.2:2900"

How follower writes are forwarded

KalamDB uses Multi-Raft groups, so a client can send a write to any reachable node.

For the full architecture, see /docs/server/architecture/clustering and /docs/server/architecture/table-types.

Example:

1kalam --url http://node-2:2900 --command "INSERT INTO app.messages (id, body) VALUES (101, 'hello')"

Assume the authenticated or effective user is user-42, and that user hashes to DataUserShard(7).

1. The request can land on node 2 even if node 2 is only a follower for DataUserShard(7).
2. KalamDB prepares and classifies the SQL once, then derives the target Raft group from the table type and current user_id.
3. For user and stream tables, the target group is selected by hashing user_id into one of cluster.user_shards groups.
4. If the receiving node is not leader for that target group, it forwards the original SQL, params, auth header, and request id over gRPC to the leader of that group.
5. The leader executes the write, appends it to that group’s Raft log, replicates it to followers, commits it, and returns the result.
6. The follower returns that leader-built response to the client.

This means the client does not need to discover the right leader first.

Multi-Raft routing today

• KalamDB runs one metadata Raft group plus multiple user data groups.
• User and stream data are routed by user_id, so all data for one user is coordinated by the same user-data group leader at a given time instead of scattering that user’s active writes across many leaders.
• That locality keeps the cluster faster by reducing cross-group coordination and improving write-path locality.
• Shared tables are not meaningfully sharded yet. Today they route to a single shared data group.
• Better shared-table partitioning is a work in progress. The planned direction is partition-by-key so each shared table can define how rows are partitioned and where they belong.

Credential and instance management

The top-level commands (kalam login, logout, whoami, token create) are the preferred operator surface now. The flags below are still available for compatibility and scripting.

Examples:

1kalam --list-instances2kalam --show-credentials --instance dev3kalam --update-credentials --instance dev --url http://localhost:2900 --user admin4kalam --delete-credentials --instance dev

Live query subscription options

The CLI live-query surface is \live <SELECT ...> in interactive mode and --subscribe "<SELECT ...>" in non-interactive mode. Both routes send a SELECT plus an optional trailing OPTIONS (...) clause to the WebSocket subscription path.

Supported CLI subscription options today:

Options can be combined in one clause, for example OPTIONS (last_rows=20, batch_size=5, from=1234).

Examples:

1kalam --subscribe "SELECT * FROM app.messages WHERE conversation_id = 7 OPTIONS (batch_size=5)"2kalam --subscribe "SELECT * FROM app.messages OPTIONS (last_rows=20)" --subscription-timeout 153kalam --subscribe "SELECT * FROM app.messages OPTIONS (last_rows=20, batch_size=5, from=1234)"

Interactive examples:

1kalam> \live SELECT * FROM app.messages OPTIONS (batch_size=5);2kalam> \subscribe SELECT * FROM app.messages OPTIONS (last_rows=20);3kalam> \live SELECT * FROM app.messages OPTIONS (last_rows=20, batch_size=5, from_seq_id=1234);

How to verify batching from the CLI output:

• The CLI prints a BATCH <n> line for each startup snapshot page.
• With OPTIONS (batch_size=5) and 20 matching rows, you should see four startup batches of 5 rows each.
• Startup batches are delivered from oldest to newest in normal batch mode.
• last_rows is different: it is a single-batch rewind of the newest rows, not paginated history replay.

Example output:

1[12:00:00.123] ✓ SUBSCRIBED [sub_...] 0 total rows, batch 1 (loading...), 3 columns2[12:00:00.124] BATCH 1 [sub_...] 5 rows (more pending)3  {"id":1,"message":"hello 1"}4  {"id":2,"message":"hello 2"}5[12:00:00.130] BATCH 2 [sub_...] 5 rows (more pending)6...7[12:00:00.145] BATCH 4 [sub_...] 5 rows (complete)

Topic consumer options (--consume)

Use this mode to consume topic records directly from a terminal.

Examples:

1# Read newest events and keep running2kalam --consume --topic blog.summarizer --from latest3 4# Replay from earliest with bounded run5kalam --consume --topic blog.summarizer --group summarizer-agent --from earliest --consume-limit 50 --consume-timeout 60

Schema watch options (--watch-schema)

Use this mode when your app has a local schema-generation step such as npm run schema:gen and you want the CLI to rerun it after DDL changes.

Examples:

1# Watch all non-system schemas2kalam --watch-schema --run "npm run schema:gen"3 4# Watch one namespace5kalam --watch-schema --namespace chat --run "npm run schema:gen"6 7# Watch multiple namespaces8kalam --watch-schema --namespace chat --namespace billing --run "npm run schema:gen"9 10# Watch a specific table11kalam --watch-schema --table chat.messages --run "npm run schema:gen"12 13# Run once immediately, then poll every 5s14kalam --watch-schema --namespace chat --run "npm run schema:gen" --run-on-start15 16# Faster polling17kalam --watch-schema --namespace chat --run "npm run schema:gen" --interval 2s

Internally the CLI polls system.tables and checks for rows whose updated_at is newer than the last observed watch timestamp. Repeated namespaces are combined with OR, and repeated tables are added as extra OR branches.

Timeout and runtime tuning options

Global utility options

Interactive shell commands by category

After launching interactive mode (kalam with no --command/--file), these backslash commands are available.

Core shell and inspection

Session introspection

Use \session (or \info) to inspect the current CLI process and server connection: resolved URL, user, connectivity, health probe status, server version, API version, build date, cluster mode, config file, local history, and build metadata.

\health uses the same public /health and /v1/api/healthcheck endpoints documented in the HTTP reference. It does not fall back to authenticated SQL. On remote deployments those endpoints may be localhost-only; in that case the CLI reports the restriction, while \session can still show version/build details learned from cluster metadata.

Use \sessions when you want server-side observability for PostgreSQL bridge traffic. It executes:

1SELECT *2FROM system.sessions3ORDER BY last_seen_at DESC, session_id;

That view is focused on live pg_kalam gRPC sessions only. To inspect active explicit transactions across both pg_kalam and native /v1/api/sql requests, query:

1SELECT transaction_id, owner_id, origin, state, write_count2FROM system.transactions3ORDER BY origin, transaction_id;

See /docs/server/sql-reference/system-views for the view columns and query patterns.

Namespace, schema, impersonation, and formatting

Example:

1USE NAMESPACE chat;2SELECT * FROM messages WHERE conversation_id = 42;3\flush table messages4\as user_123 SELECT * FROM app.messages WHERE conversation_id = 42;

\flush is a shortcut for STORAGE FLUSH:

• \flush or \flush all runs STORAGE FLUSH ALL using the current namespace context.
• \flush table messages runs STORAGE FLUSH TABLE chat.messages when the current namespace is chat.
• \flush table billing.invoices preserves the explicit namespace you typed.

The CLI rewrites that shortcut to the canonical SQL wrapper:

1EXECUTE AS 'user_123' (2  SELECT * FROM app.messages WHERE conversation_id = 423)

See /docs/server/sql-reference/impersonation for the delegation rules and role matrix.

Table transfer commands

Notes:

• \export and \import run asynchronous server jobs and poll until they reach a terminal state.
• The CLI shows progress while uploading import ZIP files and downloading exported ZIP files.
• Table type is inferred by the backend from table metadata; do not pass a type flag.
• For user tables, --user-id is required. If omitted, the backend returns a validation error.
• <namespace.table> is required for both commands; unqualified table names are rejected.

Examples:

1\export app.orders --output ./orders-backup.zip2\import app.orders_restored ./orders-backup.zip3\export app.user_profile --user-id user_123 --output ./profile-user123.zip4\import app.user_profile user-profile.zip --user-id user_123

Credentials in interactive mode

Live query commands

Topic consumer command (interactive)

Example:

1\consume blog.summarizer --group summarizer-agent --from earliest --limit 25 --timeout 45

Cluster and ingest control commands

The \cluster meta-command renders cluster operations directly from the CLI surface.

SQL workflows the CLI should cover

The backslash commands are only part of the surface. Many important CLI workflows are plain SQL entered through -c, -f, or the interactive shell.

Impersonation

You can use either the \as shortcut or the raw SQL form:

1EXECUTE AS 'user_123' (2  SELECT * FROM app.messages ORDER BY id DESC LIMIT 203);

Backup and user export

Run backup and export workflows as normal SQL:

1BACKUP DATABASE TO '/tmp/kalamdb-backup.tar.gz';2EXPORT USER DATA;3SHOW EXPORT;

Live queries

The CLI live-query commands take a normal SELECT and run it over the live subscription channel:

1kalam --subscribe "SELECT * FROM app.messages WHERE conversation_id = 7"

1\subscribe SELECT * FROM app.messages WHERE conversation_id = 7

There is no separate live-query SQL keyword to learn for the CLI path; use the same SELECT you would run normally.

Export user data

1EXPORT USER DATA;2SHOW EXPORT;

SHOW EXPORT returns job rows with a download_url URI path such as /v1/exports/<user_id>/<export_id>. Prefix that path with the same server base URL you used for the CLI when downloading the finished ZIP.

Backup and restore

1BACKUP DATABASE TO '/var/backups/kalamdb-nightly.tar.gz';2RESTORE DATABASE FROM '/var/backups/kalamdb-nightly.tar.gz';

Backup and restore paths are resolved on the server filesystem, not on the machine running the CLI.

• If BACKUP DATABASE TO ends with .tar.gz or .tgz, KalamDB writes a single archive file.
• If it does not, KalamDB writes the backup directory layout under that path.
• RESTORE DATABASE FROM accepts either the directory layout or a .tar.gz / .tgz archive.
• Backup and restore require a DBA or System role.
• There is no separate backup download endpoint today; the TO '<path>' value is the server-side artifact location.
• To track the status of the backup you can query the jobs table: select * from system.jobs where job_id = ‘backupjob’;

Topic pub/sub SQL

Use SQL for topic definition, CDC wiring, and explicit offset control:

1CREATE TOPIC app.new_messages PARTITIONS 4;2ALTER TOPIC app.new_messages ADD SOURCE app.messages ON INSERT WITH (payload = 'full');3CONSUME FROM app.new_messages GROUP 'worker-1' FROM EARLIEST LIMIT 100;4ACK app.new_messages GROUP 'worker-1' UPTO OFFSET 99;5DROP TOPIC app.new_messages;

The --consume flag and \consume command are convenience shells around topic consumption. Use raw CONSUME FROM and ACK when you want explicit SQL-based control or when you are scripting the workflow.

Quick command map

1# Interactive shell2kalam3 4# One-shot SQL5kalam -c "SELECT * FROM system.tables LIMIT 5;"6 7# File execution8kalam -f ./queries.sql9 10# Live subscription11kalam --subscribe "SELECT * FROM app.messages"12 13# Table export/import via meta-commands (one-shot)14kalam -c "\\export app.orders --output ./orders-backup.zip"15kalam -c "\\import app.orders_restored ./orders-backup.zip"16 17# Start in one namespace, then use unqualified table names interactively18kalam19# inside the shell:20# USE NAMESPACE chat;21# SELECT * FROM messages;22# \flush table messages23 24# Export user data and inspect download paths25kalam -c "EXPORT USER DATA;"26kalam -c "SHOW EXPORT;" --json27 28# Server-side backup archive29kalam -c "BACKUP DATABASE TO '/var/backups/kalamdb-nightly.tar.gz'"30 31# Restore from a server-side archive32kalam -c "RESTORE DATABASE FROM '/var/backups/kalamdb-nightly.tar.gz'"33 34# Topic consumer35kalam --consume --topic blog.summarizer --group summarizer-agent --from latest36 37# Regenerate local Drizzle schema on DDL changes38kalam --watch-schema --namespace app --run "npm run schema:gen" --run-on-start

Related docs

• /docs/server/getting-started/authentication
• /docs/server/getting-started/configuration
• /docs/server/sql-reference
• /docs/ts-sdk/consumers
• /docs/ts-sdk/orm