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 agent scaffolding.

Install and verify

Choose one of these installation options:

Option 1: install.sh (recommended)

curl -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

cd cli
cargo build --release
./target/release/kalam --help

After installation, verify your CLI:

kalam --help
kalam --version

Execution modes and precedence

kalam supports four execution modes:

1. --init-agent: generate a TypeScript agent scaffold and exit.
2. --subscribe / --list-subscriptions / --unsubscribe: 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:

• --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 used.
• 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:8080.

Query execution and output options

Examples:

kalam --command "SELECT * FROM system.tables LIMIT 5;"
kalam --command "SELECT * FROM system.tables LIMIT 5;" --json
kalam --file ./setup.sql --csv

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:

kalam --command "\\cluster list"
kalam --command "\\cluster list groups"
kalam --command "\\cluster rebalance"
kalam --command "\\cluster join 2 10.0.0.2:9188 http://10.0.0.2:8080"

How follower writes are forwarded

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

Example:

kalam --url http://node-2:8080 --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:

kalam --list-instances
kalam --show-credentials --instance dev
kalam --update-credentials --instance dev --url http://localhost:8080 --user admin
kalam --delete-credentials --instance dev

Live query subscription options

Examples:

kalam --subscribe "SELECT * FROM app.messages WHERE conversation_id = 7"
kalam --subscribe "SELECT * FROM app.messages" --subscription-timeout 120 --initial-data-timeout 15

Topic consumer options (--consume)

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

Examples:

# Read newest events and keep running
kalam --consume --topic blog.summarizer --from latest
 
# Replay from earliest with bounded run
kalam --consume --topic blog.summarizer --group summarizer-agent --from earliest --consume-limit 50 --consume-timeout 60

Agent scaffolding options (--init-agent)

The CLI can generate a ready-to-run TypeScript summarizer-style agent project.

Scaffold defaults:

• table: blog.blogs
• topic: <namespace>.<table>_agent
• group: <project-name-slug>-group
• id/input/output columns: blog_id, content, summary

Example:

kalam \
  --init-agent \
  --init-agent-non-interactive \
  --agent-name summarizer-agent \
  --agent-output ./examples \
  --agent-table blog.blogs \
  --agent-topic blog.summarizer \
  --agent-group blog-summarizer-agent \
  --agent-id-column blog_id \
  --agent-input-column content \
  --agent-output-column summary

Create a sample agent with CLI

Use the command above (or kalam --init-agent interactive mode), then:

cd ./examples/summarizer-agent
npm install
npm run start

If you want the published TypeScript SDK packages, install them from npm:

npm install @kalamdb/client @kalamdb/consumer

Package references:

• @kalamdb/client on npm 
• @kalamdb/consumer on npm 

Generated src/agent.ts shape

The scaffold generates an agent.ts that wires runAgent() with retries and failure handling:

import { Auth } from '@kalamdb/client';
import { createConsumerClient, runAgent } from '@kalamdb/consumer';
 
const client = createConsumerClient({
  url: process.env.KALAMDB_URL ?? 'http://127.0.0.1:8080',
  authProvider: async () => Auth.basic(
    process.env.KALAMDB_USER ?? 'root',
    process.env.KALAMDB_PASSWORD ?? 'kalamdb123',
  ),
});
 
await runAgent<Record<string, unknown>>({
  client,
  name: 'summarizer-agent',
  topic: process.env.KALAMDB_TOPIC ?? 'blog.summarizer',
  groupId: process.env.KALAMDB_GROUP ?? 'blog-summarizer-agent',
  start: 'earliest',
  batchSize: 20,
  retry: {
    maxAttempts: 3,
    initialBackoffMs: 250,
    maxBackoffMs: 1500,
    multiplier: 2,
  },
  onRow: async (ctx, row) => {
    // Read row, generate summary, and write summary column.
  },
  onFailed: async (ctx) => {
    // Persist terminal failures to failure table.
  },
  ackOnFailed: true,
});

Agent example references

• Summarizer Agent docs
• examples/summarizer-agent 
• examples/chat-with-ai 

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, cluster mode, config file, local history, and build metadata.

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

SELECT *
FROM system.sessions
ORDER 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:

SELECT transaction_id, owner_id, origin, state, write_count
FROM system.transactions
ORDER BY origin, transaction_id;

See System Views for the view columns and query patterns.

Schema and formatting

Credentials in interactive mode

Live query commands

Topic consumer command (interactive)

Example:

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

Cluster and ingest control commands

The \cluster meta-command mirrors the current backend cluster SQL. \cluster join and \cluster leave remain shell placeholders only; SQL CLUSTER JOIN and CLUSTER LEAVE were removed from the server.

Quick command map

# Interactive shell
kalam
 
# One-shot SQL
kalam -c "SELECT * FROM system.tables LIMIT 5;"
 
# File execution
kalam -f ./queries.sql
 
# Live subscription
kalam --subscribe "SELECT * FROM app.messages"
 
# Topic consumer
kalam --consume --topic blog.summarizer --group summarizer-agent --from latest
 
# Generate agent scaffold
kalam --init-agent

Related docs

• Authentication
• Configuration
• SQL Reference
• TypeScript Consumers
• Summarizer Agent Example