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

Credential and instance management

Examples:

kalam --list-instances
kalam --show-credentials --instance dev
kalam --update-credentials --instance dev --url http://localhost:8080 --username 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 SDK package, install it from npm:

npm install kalam-link

Package reference: kalam-link on npm 

Generated src/agent.ts shape

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

import { Auth, createClient, runAgent } from 'kalam-link';
 
const client = createClient({
  url: process.env.KALAMDB_URL ?? 'http://127.0.0.1:8080',
  auth: Auth.basic(
    process.env.KALAMDB_USERNAME ?? '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

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

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