Klavex CLI

Klavex pulls your team's environment variables from an encrypted vault and injects them into a child process at runtime. Nothing is written to a .env file — so the secrets never sit on disk where a coding agent could read them.

Quickstart

From zero to a running app with secrets injected:

$ pip install klavex $ klavex login # opens your browser to authenticate $ klavex init # pick your project + environment once $ klavex run -- npm start # secrets injected into just this process

That's it. klavex init pins your project and environment to this directory (in a .klavex file), so klavex run needs no flags. The variables are injected into the npm start process only — your shell, and every file on disk, stays clean.

Install

Klavex is a Python package. It needs Python 3.10+ and works on macOS, Linux, and WSL.

$ pip install klavex

This installs two equivalent entry points — klavex and the shorter kx. Verify it:

$ klavex --version

Log in

klavex login opens your browser to authenticate and stores a token in your system keychain (via keyring) — no API keys to paste or leak.

$ klavex login → opens https://app.klavex.dev/cli/… ✓ Logged in as sam@team

No browser on hand? --no-browser prints the URL instead of opening it, so you can approve from another device:

$ klavex login --no-browser # prints the URL to open elsewhere

For fully headless principals — CI runners and agent seats — skip interactive login entirely and authenticate with a KLAVEX_TOKEN (see Agents & CI below).

Check who you're logged in as, or sign out:

$ klavex whoami $ klavex logout

Run a command

klavex run fetches the variables for an environment, then spawns your command with them set in its process environment. The parent shell never sees them, and nothing is written to disk.

$ klavex run -p "My App" -e Production -- node server.js → injecting 7 secrets into child process ✓

Everything after -- is the command to run, passed through untouched. -p (project) and -e (environment) accept either a backend ID (proj_…, env_…) or a human name, matched case-insensitively:

$ klavex run -e env_dev_abc123 -- npm test $ klavex run -p "My App" -e Development -- npm run dev

Why --? It tells Klavex where its own flags stop and your command begins, so flags like npm test --watch are forwarded to npm, not parsed by klavex.

--no-inherit

By default the child also inherits your current shell environment. Pass --no-inherit to give it only the fetched variables and nothing else:

$ klavex run --no-inherit -e Production -- ./deploy.sh

All commands

Command	What it does
klavex login	Authenticate via browser and store a token in your keychain.
klavex logout	Remove the stored token from this machine.
klavex whoami	Show the currently authenticated user.
klavex status	Show login state, API URL, and the active project pin.
klavex init	Write a `.klavex` pin in the current directory so `run` needs no flags.
klavex projects	List the projects you have access to.
klavex envs	List environments for a project.
klavex vars	List the variable keys in an environment.
klavex run … -- <cmd>	Inject an environment's variables into a child process.

Run any command with --help for its full flag list, e.g. klavex run --help.

Project pinning

Tired of typing -p and -e every time? Run klavex init once in your project directory. It writes a small .klavex file that pins a default project and environment, so run can be flag-free:

$ klavex init → pinned My App / Production · .klavex written ✓ $ klavex run -- npm start # uses the pin in this directory

The .klavex file holds only IDs (no secrets), so it's safe to commit. You can still override it per-run with -p / -e.

CI & Docker

klavex run is just a process wrapper, so it drops into any pipeline. Set a KLAVEX_TOKEN (from an agent seat) and wrap your build or deploy step — no interactive login:

# GitHub Actions / GitLab CI step $ export KLAVEX_TOKEN=kx_agent_... $ klavex run -e env_xxx -- ./deploy.sh # Inside a Docker entrypoint (KLAVEX_TOKEN passed as an env var) ENTRYPOINT ["klavex", "run", "-e", "env_xxx", "--", "node", "server.js"]

Use environment IDs (env_xxx) with agent tokens — name lookups hit team-level endpoints a scoped token can't read.

Configuration

By default the CLI talks to the production API. Point it at a local or staging backend with an environment variable:

$ export KLAVEX_API_URL=http://localhost:8000 $ klavex whoami

KLAVEX_API_URL — override the API base URL.
KLAVEX_TOKEN — authenticate non-interactively with a token (for agent seats and CI). Takes precedence over the keychain and works where no OS keychain exists.
Tokens from klavex login are stored in your OS keychain via keyring, not in a plaintext file.

Agents & CI

For an agent seat (minted in the dashboard) or a CI runner, there's no browser for klavex login. Pass the token via the environment instead:

$ export KLAVEX_TOKEN=kx_agent_... $ klavex run -e env_xxx -- npm test # scoped to the envs you granted

Use environment IDs (env_xxx) or a committed .klavex pin for agents — name lookups hit team-level endpoints a scoped agent token can't read.

Troubleshooting

Not authenticated

Run klavex login first. If a token expired, logging in again refreshes it.

Looking up env by name requires -p

When you pass -e as a name (not an env_… ID), Klavex needs to know which project to search. Add -p <project>, or run klavex init to pin one.

Nothing to run

Pass a command after --: klavex run -e Production -- npm start.

Still stuck?

Add --debug to any command for a full traceback, or email support@klavex.dev.