Skip to main content
Every Kelviq organization has a sandbox environment alongside production — see the sandbox guide. The CLI is sandbox-first: every command targets sandbox unless you explicitly pass --prod.
There is deliberately no configuration that makes an unqualified command touch production — --prod is always explicit, per command. The one command that inherently targets production, kelviq promote, says so in its name, shows you the full diff of what production would change, and requires confirmation before writing (plus a typed production confirmation before any --prune archive). Promote needs both keys configured: sandbox to read, production to write. Each environment has its own API host and its own keys — the CLI selects both together: Always pair the key with its own environment’s host — a key from one environment doesn’t belong on the other’s host, and the CLI never mixes them.

​
Getting keys

The CLI authenticates with Server API Keys from the dashboard:
  1. Sign in at app.kelviq.com.
  2. Go to Settings → API keys.
  3. Copy the Server API Key for the environment you want (sandbox and production have separate keys).
Server API Keys have full API access. Never expose them in client-side code, commit them to version control, or paste them into shared chats. The CLI never echoes or logs a key.

​
Key storage

kelviq login stores keys in a per-user config file:
  • The file is created with owner-only permissions (0600), inside a 0700 directory.
  • XDG_CONFIG_HOME is respected if set (the file lives at $XDG_CONFIG_HOME/kelviq/config.json).
  • Sandbox and production keys are stored as separate entries; kelviq logout removes them individually (--prod) or together (--all).

​
Environment variables

Environment variables override the stored config file — useful for CI, containers, and one-off overrides without touching your stored keys. They can come from the shell or from the project’s env file: before every command, the CLI reads KELVIQ_* variables from .env.local and then .env in the working directory, never overriding a variable the shell already sets. Pass --env-file <path> to read a specific file instead, or --no-env-file to read none. kelviq env lists the files it read. KELVIQ_SERVER_API_KEY and KELVIQ_ENV work the same way as in the MCP server; the environment-named keys are CLI-only.
  • A variable named for an environment wins over KELVIQ_SERVER_API_KEY. Use KELVIQ_SANDBOX_SERVER_API_KEY and KELVIQ_PRODUCTION_SERVER_API_KEY when one shell needs both keys, for example for kelviq promote.
  • KELVIQ_ENV only decides which environment KELVIQ_SERVER_API_KEY belongs to. It never makes a command target production — only --prod does.
  • Any value other than sandbox or production makes commands fail rather than guess.
A typical CI setup skips kelviq login entirely:
For kelviq promote in CI, set both KELVIQ_SANDBOX_SERVER_API_KEY and KELVIQ_PRODUCTION_SERVER_API_KEY instead. If a command needs a key and finds none — neither in the environment nor stored — it fails with a message naming the variables to set and where to get a key. If KELVIQ_SERVER_API_KEY is set for the other environment, the message says so.

​
Checking your setup

kelviq env prints the full picture without calling the API, and kelviq env --check adds one authenticated read per configured key:
set means a key is configured (stored, from an env file, or from the shell) — not that it’s valid. kelviq env --check verifies each key with one read against its own environment and exits non-zero if any configured key is rejected. Kelviq has no key-introspection endpoint yet, so the CLI can’t display your organization name.