Kdbx

kdbx — KeePassXC credentials skill

Manage a project's secrets in per-project, per-env KeePassXC vaults (<keepassxc-dir>/<project>/<env>.kdbx, key-file-only, KDBX4+Argon2) and get them into tools without printing them into the transcript, logs, or shell history.

When to use

• A project needs to store / retrieve / rotate secrets, API keys, or tokens.
• You need to run a command that requires secrets in its env (kdbx run -- …).
• You're replacing a .env file with a managed source of truth.

Discovery is automatic: kdbx walks up from the cwd to a committed .keepassxc.json (see references/schema.md). Active env = --env › $KDBX_ENV › the pointer's defaultEnv.

Invocation

kdbx is a standalone binary. Check it is present, and install it if not:

kdbx --version    # if this fails, install:
curl -LsSf https://raw.githubusercontent.com/yarrasys/kdbx/main/install.sh | sh

Then invoke operations directly from the project directory:

kdbx <op> [args]

Discovery is automatic: kdbx walks up from the cwd to a committed .keepassxc.json. Active env = --env › $KDBX_ENV › the pointer's defaultEnv.

Other install methods: brew install yarrasys/tap/kdbx, go install github.com/yarrasys/kdbx@latest (Go 1.25+), or the ghcr.io/yarrasys/kdbx container image.

Legacy (uv) fallback. The original Python implementation still lives at skills/kdbx/kdbx.py and is invoked as uv run --locked <SKILL_DIR>/kdbx.py <op>. It is frozen as the reference implementation, receives bug fixes only, and will be archived at kdbx v1.0. Prefer the binary.

Operations

--json is a global flag: it renders machine-readable output for the read operations (get / list / check / envs).

Op	Use
init [--env E]	create the vault + keyfile for an env (refuses to overwrite; 0600)
set PATH [--var NAME] [--from-env VAR] [--raw]	store a secret (value via stdin/--from-env, never argv); optionally register a var mapping
get PATH [--reveal|--clip]	masked by default; --reveal prints; --clip copies (auto-clears)
list [GROUP]	list entry paths (never values; excludes Recycle Bin)
delete PATH [--purge]	soft-delete to Recycle Bin; --purge removes permanently
mv OLD NEW	rename/move an entry; rewrites affected var mappings
run [--env E] -- CMD…	inject the env's mapped vars into a child process and exec it
export [--out F]	render mapped vars as a 0600 dotenv (for tools that need a file)
import FILE	read an existing .env into the vault + var map
check	verify every mapped var resolves (non-zero exit on drift)
envs	list configured envs; mark the active one
rekey [--env E]	rotate the keyfile
mcp	run a read-only MCP server over stdio (kdbx_list/envs/check/get-masked/run)
guard --hook pretooluse	evaluate a PreToolUse hook payload on stdin; deny agent-issued human-only ops

Exit codes: 0 ok · 2 not-found · 3 locked/keyfile-missing · 4 destructive op not confirmed (delete --purge / rekey without an interactive y) · 5 drift · 6 vault-changed · 7 runtime.

Roles — who runs what

🔑 The agent reads and uses secrets; the human performs writes.

• Agent (you, in this session): run, get (masked), list, check, envs, init. For anything that mutates the vault (set / delete / mv / import / rekey) or exposes a value (get --reveal / --clip, export), emit the exact command for the human to run in their own terminal (or via !kdbx … in this prompt) — do not run it yourself.
• Human: runs those write/expose commands; irreversible ones (delete --purge, rekey) ask for an interactive y/N.
• The kdbx plugin enforces this with a PreToolUse hook (your write commands are blocked; the human's ! commands pass through untouched). The bare skill states it as a contract.
• The real prod boundary is key-file possession, not a name match — you can only reach an env's secrets if its key file exists on this machine.

Security — do / don't (read before using)

• 🔑 Never author or observe a secret value. Your job is the entry PATH / var-name only. To store a value, the human runs set and pipes the secret on their terminal (kdbx set api/openai < secret.txt, or types it at the getpass prompt).
• ❌ Never do echo SECRET | kdbx set … or export SECRET=…; kdbx set --from-env SECRET inside this session — that puts the plaintext in the transcript. Both are forbidden.
• Prefer kdbx run -- <cmd> (inject, never print) over export/get --reveal.
• The keyfile is the sole secret; losing it makes the vault unrecoverable. Back it up out-of-band.

References

• references/schema.md — the full .keepassxc.json schema + path grammar.
• references/fallback.md — read-only keepassxc-cli commands (per-OS binary locations).
• references/security.md — threat model, trust boundary, rotation / leak runbook.