CLI Guide
The kalam CLI is KalamDB’s interactive terminal client (built on kalam-link).
Use it for one-off SQL execution, interactive query sessions, and live subscriptions.
Install and verify
If you build from source:
cd cli
cargo build --release
./target/release/kalam --helpIf kalam is already in your PATH:
kalam --helpConnect to a server
# Default (uses saved credentials/config, otherwise localhost)
kalam
# Explicit URL
kalam --url http://localhost:8080
# Host/port alternative
kalam --host localhost --port 8080
# Basic auth
kalam --username alice --password Secret123!
# JWT auth
kalam --token "<JWT_TOKEN>"
# Save credentials for future sessions
kalam --username alice --password Secret123! --save-credentials --instance devInteractive Mode
Once connected, you’ll get a kalam> prompt where you can execute SQL directly:
kalam> SHOW NAMESPACES;
kalam> CREATE NAMESPACE myapp;
kalam> SHOW TABLES IN myapp;You can also run non-interactive commands:
# One SQL statement and exit
kalam -c "SELECT * FROM system.tables LIMIT 5;"
# Run SQL from file and exit
kalam -f setup.sqlLive subscriptions
Start a live query from the prompt:
kalam> \subscribe SELECT * FROM app.messages WHERE user_id = 'alice';Or from non-interactive mode:
kalam --subscribe "SELECT * FROM app.messages WHERE user_id = 'alice';"Press Ctrl+C to stop streaming output.
Output formats
table(default): human-readable table with summaryjson: raw JSON rowscsv: CSV output for piping/scripts
kalam --command "SELECT * FROM app.messages LIMIT 10;" --format jsonKey command-line flags
--url,-u: server URL--host,-Hand--port,-p: host/port alternative to--url--instance: credential profile name (defaultlocal)--username/--password: basic auth--token: JWT bearer auth--save-credentials: save credentials for current instance--show-credentials: display stored credentials for instance--update-credentials: login and update stored credentials--delete-credentials: remove stored credentials for instance--list-instances: list stored credential instances--format:table,json, orcsv--json/--csv: format shorthand--file,-f: execute SQL file--command,-c: execute SQL statement--subscribe <SQL>: run a live query subscription--subscription-timeout: subscription idle timeout (seconds)
Interactive \ commands
| Command | Description |
|---|---|
\help, \? | Show help |
\quit, \q | Exit CLI |
\info, \session | Show session info |
\dt, \tables | List tables |
\d <table>, \describe <table> | Describe table |
\stats, \metrics | Show system stats |
\health | Server healthcheck |
| `\format table | json |
\subscribe <SQL>, \watch <SQL> | Start live subscription |
\refresh-tables, \refresh | Refresh autocomplete metadata |
\show-credentials, \credentials | Show stored credentials |
\update-credentials <u> <p> | Update stored credentials |
\delete-credentials | Delete stored credentials |
Multiple instances
# Configure separate instances
kalam --update-credentials --instance dev --username dev_user
kalam --update-credentials --instance staging --username staging_user
kalam --update-credentials --instance prod --username prod_admin
# Connect by instance profile
kalam --instance dev
kalam --instance staging
kalam --instance prodPractical examples
# Export aggregate data as JSON
kalam --instance prod \
--command "SELECT country, COUNT(*) AS users FROM users GROUP BY country" \
--format json \
--no-color > stats.json# File upload helper inside SQL
INSERT INTO chat.uploads (id, name, attachment)
VALUES ('doc2', 'CLI Doc', file('/Users/user/document1.pdf', 'text/plain'));Next steps
- Quick Start for initial server setup
- SQL Reference for full query syntax
- API Reference for HTTP and integration endpoints
Last updated on