Kalam CLI Command Reference

The Kalam CLI (kalam) is the SQL-first terminal client for KalamDB. This guide documents every CLI flag and interactive command currently implemented in ../KalamDB/cli, including live subscriptions, topic consumers, credential workflows, and schema watch automation.

Install and verify

Choose one of these installation options:

Option 1: install.sh (recommended)

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

Option 2: GitHub release binaries

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

• GitHub Binaries

Option 3: Build from source

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

After installation, verify your CLI:

1kalam --help2kalam --version

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.

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.

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

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 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 Execute As for the delegation rules and role matrix.

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# Start in one namespace, then use unqualified table names interactively14kalam15# inside the shell:16# USE NAMESPACE chat;17# SELECT * FROM messages;18# \flush table messages19 20# Export user data and inspect download paths21kalam -c "EXPORT USER DATA;"22kalam -c "SHOW EXPORT;" --json23 24# Server-side backup archive25kalam -c "BACKUP DATABASE TO '/var/backups/kalamdb-nightly.tar.gz'"26 27# Restore from a server-side archive28kalam -c "RESTORE DATABASE FROM '/var/backups/kalamdb-nightly.tar.gz'"29 30# Topic consumer31kalam --consume --topic blog.summarizer --group summarizer-agent --from latest32 33# Regenerate local Drizzle schema on DDL changes34kalam --watch-schema --namespace app --run "npm run schema:gen" --run-on-start

Related docs

• Authentication
• Configuration
• SQL Reference
• TypeScript Consumers
• Drizzle ORM & Generator