Authentication
Top-level auth commands
| Command | Behavior |
|---|---|
kalam login | Saves access and refresh tokens for --instance unless --no-save |
kalam whoami | Calls /v1/api/auth/me with resolved credentials |
kalam logout | Deletes credentials for one instance; --all clears every stored instance |
kalam token create | Creates a service user and prints access/refresh tokens for automation |
When kalam login succeeds in an interactive terminal, the CLI drops into the SQL shell. With non-interactive stdin/stdout, login exits after saving credentials.
Connection options
| Option | Description |
|---|---|
-u, --url <URL> | Full server URL or bare host. Loopback defaults to http://; other bare hosts default to https://. |
-H, --host <HOST> | Host-only alternative; combines with --port. |
-p, --port <PORT> | Port with --host (default 3000). |
--token <JWT> | JWT auth token. |
--user <USER> | User/password login identifier. |
--password [PASS] | Basic auth password; prompts when omitted in interactive mode. |
--instance <NAME> | Credential profile name (default local). |
URL resolution order:
- Normalized
--urlif set (rejects embedded credentials, query params, fragments) http://<host>:<port>when--hostis set- Stored credentials URL for the selected
--instance - Fallback
http://localhost:2900
Bare --url inputs like localhost:2900 default to http://; hosts like kalam.masky.app default to https://.
Named instances
Use separate profiles for dev, staging, and prod:
OIDC login modes
KalamDB exposes one configured external OIDC provider.
Browser login with PKCE
Opens the provider login page, listens on http://127.0.0.1:8787/callback, and exchanges the code through KalamDB.
Direct device login
For providers with a device authorization endpoint when you do not want a local browser callback.
Brokered device login
When the CLI host can reach KalamDB but not the OIDC provider directly. --brokered requires --no-browser.
kalam login --no-save ... skips writing credentials to disk.
Credential flags (scripting)
| Option | Description |
|---|---|
--list-instances | List stored credential instances. |
--show-credentials | Show stored credentials for --instance. |
--update-credentials | Login and refresh JWT/refresh token for --instance. |
--delete-credentials | Delete credentials for --instance. |
--save-credentials | Save credentials after successful user/password login. |
Interactive equivalents: \show-credentials, \update-credentials, \delete-credentials.
Project workflow (kalam init / kalam dev)
kalam init writes .env with KALAM_PROFILE=kalam-dev (pattern: kalam-<env> from [project].default_env). Workflow commands load that profile from ~/.kalam/ — not from kalam.toml.
| Scenario | What happens |
|---|---|
Local kalam dev (new server) | After the server is healthy, the CLI logs in as root using kalam/server/server.toml (auth.root_password) or mypass on loopback, then saves JWT credentials for kalam-dev |
Local kalam dev (server already running) | Precheck verifies saved credentials for KALAM_PROFILE |
Remote kalam dev (auto_start_db = false) | Precheck requires valid saved credentials — run kalam login --instance kalam-dev (or your env profile) first |
Override the profile per shell with KALAM_PROFILE in .env or the environment.