kdbx

kdbx — per-project secrets in KeePassXC vaults, safe to hand an AI agent

kdbx keeps a project's secrets in a per-project, per-environment KeePassXC vault (KDBX4, unlocked by a key file only — no master password) and gets them into the tools that need them without kdbx ever printing them into a transcript, a log file, or your shell history. Discovery is automatic: kdbx walks up from your current directory to a committed .keepassxc.json pointer file, works out which environment is active, and takes it from there. The headline command is kdbx run -- , which resolves that environment's variable mappings and injects them into a child process' environment. It replaces .env files as the source of truth; the vault stays outside the repo, so there is nothing secret to accidentally commit.

Every install method below is live — the curl installer, Homebrew, go install, the

ghcr.io container image, and the signed release archives (SHA256SUMS + cosign, with

reproducible builds). The badge above tracks the current version.

Install

# curl installer — downloads the release archive, verifies its SHA-256, installs to

~/.local/bin (override with KDBX_INSTALL_DIR; pin with KDBX_VERSION=v0.3.2)

curl -LsSf https://raw.githubusercontent.com/yarrasys/kdbx/main/install.sh | sh

brew install yarrasys/tap/kdbx                    # Homebrew

go install github.com/yarrasys/kdbx@latest # from source, needs Go 1.26+ docker run --rm ghcr.io/yarrasys/kdbx:latest --version # container (FROM scratch)

Windows: download the _windows_ archive from the releases page and put kdbx.exe on your PATH.

Building from source needs Go 1.26 or newer. Go 1.25 left support when Go 1.27 shipped, and current golang.org/x/term releases declare a 1.26 floor. Release binaries are static and impose no toolchain requirement on users.

Shell completions:

kdbx completion zsh  > "${fpath[1]}/_kdbx"

kdbx completion bash > /etc/bash_completion.d/kdbx kdbx completion fish > ~/.config/fish/completions/kdbx.fish kdbx completion powershell | Out-String | Invoke-Expression

Quick start

1. Commit a pointer file at the repo root. It names the project and its environments; it contains no secrets, so it is safe to check in.

{

"project": "demo", "defaultEnv": "dev", "envs": { "dev": {}, "prod": {} } }

An empty env object is fine — kdbx derives the artifact paths from the project and environment name: /demo/dev.kdbx and /demo/dev.keyx, where is $KEEPASSXC_DIR if set, else %LOCALAPPDATA%\keepassxc on Windows, else $XDG_CONFIG_HOME/keepassxc or ~/.config/keepassxc. Set vault and keyFile explicitly if you want them somewhere else; both accept a ${KEEPASSXC_DIR} token and a leading ~.

2. Create the vault and its key file.

$ kdbx init

ACTIVE ENV: dev vault=/home/you/.config/keepassxc/demo/dev.kdbx (source: pointer) created /home/you/.config/keepassxc/demo/dev.kdbx KEYFILE: /home/you/.config/keepassxc/demo/dev.keyx — back this up; losing it makes the vault unrecoverable.

3. Store a secret and map it to an environment variable. The value never appears on the command line — it arrives on stdin, from --from-env, or from an interactive prompt.

$ kdbx set api/openai --var OPENAI_API_KEY < secret.txt

ACTIVE ENV: dev vault=/home/you/.config/keepassxc/demo/dev.kdbx (source: pointer) modified tracked file .keepassxc.json — review and commit

--var records the mapping in the pointer file, preserving existing key order so the diff stays reviewable:

"dev": {

"vars": { "OPENAI_API_KEY": "api/openai" } }

4. Run something with the secrets injected.

kdbx run -- claude              # the author's actual daily use

kdbx run -- npm test kdbx --env prod run -- ./deploy.sh

The child inherits your environment plus the mapped variables. Its exit code is passed straight back out. Nothing is written to disk, and the value never appears in your shell history.

Reading is deliberately boring:

$ kdbx list

api/openai $ kdbx get api/openai (set, hidden) $ kdbx check # every mapping still resolves → exit 0, no output $ kdbx envs

• dev prod

Operations

Every operation accepts --env NAME. Read operations additionally accept --json. Operations marked ✦ print the banner ACTIVE ENV: vault= (source: ) to stderr; pure display operations do not.

Integration surfaces:

--json

--json gives read operations a machine-readable stdout. Secret values are never included.

$ kdbx --json list

{"entries":["api/openai"]} $ kdbx --json envs {"envs":[{"name":"dev","active":true}],"source":"pointer"} $ kdbx --json check {"missing":[],"ok":true} $ kdbx --json get api/openai {"path":"api/openai","set":true}

--json with --reveal is rejected (exit 7). On failure, stdout carries {"error":{"op":"check","exit":5,"kind":"Drift"}} alongside the usual stderr line and exit code.

Entry paths

An entry path is group/sub/Title[:field]. The field defaults to password. The reserved field names — title, username, password, url, notes, matched case-insensitively — map to the KeePass entry's native attributes; anything else becomes a protected custom property. More than one :, an empty field after :, or an empty / segment is rejected. Variable names passed to --var must match ^A-Z_*$.

Environment selection

--env beats $KDBX_ENV, which beats the pointer's defaultEnv, which defaults to dev. kdbx envs and the banner report which of the three won. An environment that isn't in the pointer file is an error (exit 2).

Exit codes

Failures print exactly one stderr line and never a stack trace or a secret. The line carries the stable kind plus kdbx's own message, which is written so that no secret value can ever appear in it:

$ kdbx get api/nope

kdbx: get failed: NotFound: entry not found: api/nope

The text of an underlying third-party error is never shown, since it is not under that rule. Set KDBX_DEBUG=1 to additionally get the full error chain and stack on stderr.

Environment variables kdbx reads: KDBX_ENV, KEEPASSXC_DIR, XDG_CONFIG_HOME, LOCALAPPDATA, KDBX_DEBUG.

Roles — agents read, humans write

kdbx is designed to be safe to hand to a coding agent. The rule is:

• Agent-safe: run, get (masked), list, check, envs, init.
• Human-only: set, delete, mv, import, rekey, export, and get --reveal / get --clip.

An agent can *use*