{
  "markdown": "# kdbx — per-project secrets in KeePassXC vaults, safe to hand an AI agent\n\n[![ci](https://github.com/yarrasys/kdbx/actions/workflows/ci.yml/badge.svg)](https://github.com/yarrasys/kdbx/actions/workflows/ci.yml)\n[![govulncheck](https://github.com/yarrasys/kdbx/actions/workflows/govulncheck.yml/badge.svg)](https://github.com/yarrasys/kdbx/actions/workflows/govulncheck.yml)\n[![release](https://img.shields.io/github/v/release/yarrasys/kdbx?sort=semver)](https://github.com/yarrasys/kdbx/releases/latest)\n[![openssf scorecard](https://api.scorecard.dev/projects/github.com/yarrasys/kdbx/badge)](https://scorecard.dev/viewer/?uri=github.com/yarrasys/kdbx)\n[![go version](https://img.shields.io/github/go-mod/go-version/yarrasys/kdbx)](go.mod)\n[![license](https://img.shields.io/github/license/yarrasys/kdbx)](LICENSE)\n\n`kdbx` keeps a project's secrets in a **per-project, per-environment KeePassXC vault**\n(KDBX4, unlocked by a key file only — no master password) and gets them into the tools that\nneed them **without kdbx ever printing them into a transcript, a log file, or your shell\nhistory**.\nDiscovery is automatic: kdbx walks up from your current directory to a committed\n`.keepassxc.json` pointer file, works out which environment is active, and takes it from\nthere. The headline command is `kdbx run -- <cmd>`, which resolves that environment's\nvariable mappings and injects them into a child process' environment. It replaces `.env`\nfiles as the source of truth; the vault stays outside the repo, so there is nothing secret\nto accidentally commit.\n\n> Every install method below is live — the curl installer, Homebrew, `go install`, the\n> `ghcr.io` container image, and the signed release archives (`SHA256SUMS` + cosign, with\n> reproducible builds). The badge above tracks the current version.\n\n## Install\n\n```sh\n# curl installer — downloads the release archive, verifies its SHA-256, installs to\n# ~/.local/bin (override with KDBX_INSTALL_DIR; pin with KDBX_VERSION=v0.3.1)\ncurl -LsSf https://raw.githubusercontent.com/yarrasys/kdbx/main/install.sh | sh\n```\n\n```sh\nbrew install yarrasys/tap/kdbx                    # Homebrew\ngo install github.com/yarrasys/kdbx@latest        # from source, needs Go 1.25+\ndocker run --rm ghcr.io/yarrasys/kdbx:latest --version   # container (FROM scratch)\n```\n\nWindows: download the `_windows_` archive from the\n[releases page](https://github.com/yarrasys/kdbx/releases) and put `kdbx.exe` on your PATH.\n\nBuilding from source needs **Go 1.25 or newer** (the KDBX engine and `golang.org/x/term`\nboth declare a 1.25 floor). Release binaries are static and impose no toolchain\nrequirement on users.\n\nShell completions:\n\n```sh\nkdbx completion zsh  > \"${fpath[1]}/_kdbx\"\nkdbx completion bash > /etc/bash_completion.d/kdbx\nkdbx completion fish > ~/.config/fish/completions/kdbx.fish\nkdbx completion powershell | Out-String | Invoke-Expression\n```\n\n## Quick start\n\n**1. Commit a pointer file** at the repo root. It names the project and its environments;\nit contains no secrets, so it is safe to check in.\n\n```json\n{\n  \"project\": \"demo\",\n  \"defaultEnv\": \"dev\",\n  \"envs\": {\n    \"dev\": {},\n    \"prod\": {}\n  }\n}\n```\n\nAn empty env object is fine — kdbx derives the artifact paths from the project and\nenvironment name: `<keepassxc-dir>/demo/dev.kdbx` and `<keepassxc-dir>/demo/dev.keyx`,\nwhere `<keepassxc-dir>` is `$KEEPASSXC_DIR` if set, else `%LOCALAPPDATA%\\keepassxc` on\nWindows, else `$XDG_CONFIG_HOME/keepassxc` or `~/.config/keepassxc`. Set `vault` and\n`keyFile` explicitly if you want them somewhere else; both accept a `${KEEPASSXC_DIR}`\ntoken and a leading `~`.\n\n**2. Create the vault and its key file.**\n\n```console\n$ kdbx init\nACTIVE ENV: dev  vault=/home/you/.config/keepassxc/demo/dev.kdbx  (source: pointer)\ncreated /home/you/.config/keepassxc/demo/dev.kdbx\nKEYFILE: /home/you/.config/keepassxc/demo/dev.keyx — back this up; losing it makes the vault unrecoverable.\n```\n\n**3. Store a secret and map it to an environment variable.** The value never appears on\nthe command line — it arrives on stdin, from `--from-env`, or from an interactive prompt.\n\n```console\n$ kdbx set api/openai --var OPENAI_API_KEY < secret.txt\nACTIVE ENV: dev  vault=/home/you/.config/keepassxc/demo/dev.kdbx  (source: pointer)\nmodified tracked file .keepassxc.json — review and commit\n```\n\n`--var` records the mapping in the pointer file, preserving existing key order so the diff\nstays reviewable:\n\n```json\n\"dev\": {\n  \"vars\": {\n    \"OPENAI_API_KEY\": \"api/openai\"\n  }\n}\n```\n\n**4. Run something with the secrets injected.**\n\n```sh\nkdbx run -- claude              # the author's actual daily use\nkdbx run -- npm test\nkdbx --env prod run -- ./deploy.sh\n```\n\nThe child inherits your environment plus the mapped variables. Its exit code is passed\nstraight back out. Nothing is written to disk, and the value never appears in your shell\nhistory.\n\nReading is deliberately boring:\n\n```console\n$ kdbx list\napi/openai\n$ kdbx get api/openai\n(set, hidden)\n$ kdbx check          # every mapping still resolves → exit 0, no output\n$ kdbx envs\n* dev\n  prod\n```\n\n## Operations\n\nEvery operation accepts `--env NAME`. Read operations additionally accept `--json`.\nOperations marked ✦ print the banner `ACTIVE ENV: <env>  vault=<path>  (source: <src>)` to\n**stderr**; pure display operations do not.\n\n| Op | Flags | Behavior (stdout / stderr / exit) |\n|----|-------|------------------------------------|\n| `init` ✦ | `--here`, `--mode standard\\|strict` | create vault + key file; with no pointer anywhere above, or with `--here`, first writes a fresh `.keepassxc.json` in the current directory (project named after it, `dev`/`prod` envs, `dev` active) so starting a project is one command; inside another project's tree, plain `init` names the pointer file it is about to use and asks for confirmation first (TTY only, exit 4 otherwise), pointing at `--here` as the way to start a separate project; stderr `created <vault>` plus a KEYFILE backup warning; refuses to overwrite an existing vault, key file, or pointer; `--mode` records the env's policy in the pointer, and `strict` anchors it into the new vault |\n| `policy bless` ✦ | | anchor the pointer's current policy (its `policy` and `run.allow` sections) into the vault; interactive-only, like `rekey`, and denied to agents by the guard; strict `run` refuses until the anchor matches |\n| `set PATH` ✦ | `--var NAME`, `--from-env VAR`, `--raw` | value from `--from-env`, else an interactive prompt with confirmation on a TTY, else stdin (empty → error; one trailing newline stripped unless `--raw`); an empty or whitespace-only value is refused; `--var` adds the mapping to the pointer file |\n| `get PATH` | `--reveal` \\| `--clip` | default: prints `(set, hidden)` — no length or prefix leak; `--reveal` prints the value with a stderr warning; `--clip` copies it and auto-clears after ~15 s; missing entry or field → exit 2 |\n| `list [GROUP]` | | sorted `group/…/title` lines, filtered by the `GROUP` prefix, Recycle Bin excluded; never prints values |\n| `delete PATH` ✦ | `--purge` | soft-deletes to the Recycle Bin by default; `--purge` prompts `y/N` (TTY only — a non-TTY refuses with exit 4) then removes permanently |\n| `mv SRC DST` ✦ | | moves or retitles an entry, creating destination groups; re-points the active environment's var mappings that referenced `SRC`, keeping any `:field` suffix; stderr `re-pointed N var mapping(s) …` |\n| `run` ✦ | `--allow-missing`, `--no-mask`, `--any`, `-- CMD…` | if the pointer has a `run.allow` list, refuses an unlisted command before the vault is even opened (exit 7, `NotAllowed`) unless `--any`; resolves the active environment's `vars` map, injects it into the child's environment, resolves `argv[0]` through PATH (PATHEXT on Windows), forwards signals, and passes the child's exit code through; when a child stream is captured (not a TTY), injected values ≥ 8 bytes in it become `***` (`--no-mask` disables; the guard denies it for agents); no command → exit 2; an unresolved var → exit 5 unless `--allow-missing` |\n| `export` ✦ | `--out FILE`, `--allow-missing` | renders the mappings as dotenv (always double-quoted; `\\`, `\"` and newlines escaped); `--out` writes atomically at 0600 with a gitignore reminder, otherwise stdout |\n| `import FILE` ✦ | | parses a dotenv file (no `$VAR` interpolation), stores each `KEY` at `imported/KEY` and registers the mapping; stderr reminds you to delete or rotate the source file |\n| `check` | | prints `MISSING VAR -> path` per broken mapping; exit 0 when clean, 5 on drift |\n| `envs` | | one line per environment, the active one marked `* `; stderr `active: <env> (source: <src>)`; no pointer file → exit 2 |\n| `rekey` ✦ | | prompts `y/N` (TTY only, else exit 4), mints a new key file, re-keys the vault, replaces the old key file atomically; stderr reminds you to redistribute it |\n\nIntegration surfaces:\n\n| Command | Purpose |\n|---------|---------|\n| `kdbx mcp` | read-only MCP server over stdio (five tools: `kdbx_list`, `kdbx_envs`, `kdbx_check`, `kdbx_get`, `kdbx_run`) |\n| `kdbx guard --hook pretooluse` | evaluates a `PreToolUse` hook payload on stdin and denies agent-issued human-only operations |\n| `kdbx completion <shell>` | emits a completion script for bash, zsh, fish, or powershell |\n| `kdbx --version` | prints `kdbx <version>` |\n\n### `--json`\n\n`--json` gives read operations a machine-readable stdout. Secret values are never included.\n\n```console\n$ kdbx --json list\n{\"entries\":[\"api/openai\"]}\n$ kdbx --json envs\n{\"envs\":[{\"name\":\"dev\",\"active\":true}],\"source\":\"pointer\"}\n$ kdbx --json check\n{\"missing\":[],\"ok\":true}\n$ kdbx --json get api/openai\n{\"path\":\"api/openai\",\"set\":true}\n```\n\n`--json` with `--reveal` is rejected (exit 7). On failure, stdout carries\n`{\"error\":{\"op\":\"check\",\"exit\":5,\"kind\":\"Drift\"}}` alongside the usual stderr line and exit\ncode.\n\n### Entry paths\n\nAn entry path is `group/sub/Title[:field]`. The field defaults to `password`. The reserved\nfield names — `title`, `username`, `password`, `url`, `notes`, matched case-insensitively —\nmap to the KeePass entry's native attributes; anything else becomes a **protected custom\nproperty**. More than one `:`, an empty field after `:`, or an empty `/` segment is\nrejected. Variable names passed to `--var` must match `^[A-Z_][A-Z0-9_]*$`.\n\n### Environment selection\n\n`--env` beats `$KDBX_ENV`, which beats the pointer's `defaultEnv`, which defaults to `dev`.\n`kdbx envs` and the banner report which of the three won. An environment that isn't in the\npointer file is an error (exit 2).\n\n## Exit codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | success |\n| `1` | generic failure (scrubbed) |\n| `2` | not found — no pointer file, unknown environment, missing entry or field, no command given to `run` |\n| `3` | locked, key file missing, or credential failure |\n| `4` | a destructive operation was not confirmed |\n| `5` | drift — `check` found a broken mapping, or `run`/`export` could not resolve one |\n| `6` | the vault changed underneath a write; re-run |\n| `7` | preflight rejection (e.g. an invalid `--var` name, or `--json --reveal`) |\n\nFailures print exactly one stderr line and never a stack trace or a secret. The line\ncarries the stable kind plus kdbx's own message, which is written so that no secret value\ncan ever appear in it:\n\n```console\n$ kdbx get api/nope\nkdbx: get failed: NotFound: entry not found: api/nope\n```\n\nThe text of an underlying third-party error is never shown, since it is not under that\nrule. Set `KDBX_DEBUG=1` to additionally get the full error chain and stack on stderr.\n\nEnvironment variables kdbx reads: `KDBX_ENV`, `KEEPASSXC_DIR`, `XDG_CONFIG_HOME`,\n`LOCALAPPDATA`, `KDBX_DEBUG`.\n\n## Roles — agents read, humans write\n\nkdbx is designed to be safe to hand to a coding agent. The rule is:\n\n- **Agent-safe:** `run`, `get` (masked), `list`, `check`, `envs`, `init`.\n- **Human-only:** `set`, `delete`, `mv`, `import`, `rekey`, `export`, and\n  `get --reveal` / `get --clip`.\n\nAn agent can *use* a credential: `kdbx run -- npm test` works fine, and kdbx itself never\nprints the value.\n\n**This is a guardrail, not a boundary, and it is worth being precise about why.**\n\nThe binary does not enforce the split. Possession of the key file is the real boundary:\nanything that can read the key file can open the vault, whoever or whatever it is. The role\nsplit is enforced in harnesses that support hooks, by `kdbx guard`, and it is advisory\neverywhere else.\n\nThe *child* command can be pinned, if you choose to. A committed `run.allow` list in\n`.keepassxc.json` makes `run` refuse any argv not exactly on the list (a human can pass\n`--any`; the guard denies it for agents). Be clear-eyed about what that buys: the agent can\nstill edit the pointer in principle, but the guard blocks the obvious edits and the change\nis a visible diff on a tracked file instead of an invisible one-liner. Without a list,\n`run` injects into whatever argv it is handed.\n\nFor an environment that deserves ceremony (production, real customer credentials), there is\n**strict mode**: `kdbx init --mode strict`. Strict requires the allowlist, refuses `--any`\nand `--no-mask` outright, writes an audit line for every decision (command and variable\n*names*, never values, to a 0600 file next to the vault), and gates injection on a policy\nhash blessed into the vault with `kdbx policy bless` — a human-only, interactive command.\nAn out-of-band edit to the policy is refused at the next `run` instead of silently obeyed.\nThe same rules apply to the MCP server's `kdbx_run`, which additionally always masks and\nhas no escape hatches at all. A determined agent with your uid can still defeat all of\nthis; what strict changes is that quiet tampering becomes loud.\nWhen the output is captured (a pipe, an agent harness, a log), injected values in it are\nreplaced with `***` — so `kdbx run -- env` shows masks, not values, exactly where the bytes\nwere headed for a transcript. A terminal gets raw output, and `--no-mask` (denied to agents\nby the guard) restores it for piped human use. Masking matches exact values only: an agent\nthat encodes a value on the way out defeats it, as does a test script edited to exfiltrate.\nkdbx not printing a secret is a property of kdbx, not of the system it runs in.\n\nWhat the split actually buys you is that an agent does not stumble into disclosure while\ndoing something else, and cannot author, rotate or export a credential. It does not contain\nan agent that has decided to read one. If you need that, you need a boundary the agent\ncannot cross as your user: a separate account, a container, or a broker holding the keys.\nSee [issue #11](https://github.com/yarrasys/kdbx/issues/11).\n\n`kdbx guard` reads a `PreToolUse` payload on stdin and either prints a deny envelope or\nnothing at all. It **always exits 0** — it fails open, so a guard problem can never wedge\nyour agent.\n\n```console\n$ echo '{\"tool_input\":{\"command\":\"kdbx set api/openai\"}}' | kdbx guard --hook pretooluse\n{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"kdbx role-guard: 'set' is a human-only operation …\"}}\n\n$ echo '{\"tool_input\":{\"command\":\"kdbx run -- npm test\"}}' | kdbx guard --hook pretooluse\n$ echo $?\n0\n```\n\nIt blocks two things: agent-issued human-only operations, and non-kdbx programs reaching\nfor `*.kdbx` / `*.keyx` files or the KeePassXC config directory (so `cat ~/.config/keepassxc/…`\nis denied too). It recognizes `kdbx`, `keepassxc-cli` and `keepassxc` invocations as\nlegitimate.\n\n`kdbx mcp` applies the same contract to MCP clients: five tools, all read-only. There is no\nwrite tool, deliberately.\n\n## Agent and editor integration\n\nMCP server — add to `.mcp.json` (Claude Code) or your client's equivalent:\n\n```json\n{\n  \"mcpServers\": {\n    \"kdbx\": {\n      \"command\": \"kdbx\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n`PreToolUse` hook — Claude Code `settings.json` or a plugin's `hooks.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"kdbx guard --hook pretooluse\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThe [`kdbx` plugin](https://github.com/yarrasys/extensions) in `yarrasys/extensions` bundles\nboth, along with the skill documentation an agent loads to learn the contract. That repository\nis **archived and read-only** as of 2026-07-30 — the plugin still works, but it receives no\nupdates, issues or PRs. The snippets above are the whole integration; you do not need the\nplugin to wire `kdbx guard` or `kdbx mcp` into an agent.\n\n## Security\n\n- **The key file is the only secret.** There is no master password. Anyone who can read\n  `<env>.keyx` can open `<env>.kdbx`. Keep them apart from your repo — the default location\n  (`~/.config/keepassxc/<project>/`) is deliberately outside it.\n- **Back the key file up, out of band.** Losing it makes the vault unrecoverable. There is\n  no recovery path, by design.\n- **Watch out for cloud sync.** A vault or key file under OneDrive, Dropbox, iCloud Drive\n  or similar is replicated to a third party and to every device on the account. `kdbx init`\n  warns when it detects this, but does not refuse.\n- **Vault, key file and exported dotenv files are written 0600** (owner-only ACL on\n  Windows), atomically, and vault saves are crash-safe (temp file → rename, with the\n  previous vault kept as `.bak` until the rename lands).\n- **Secret values never reach argv, logs, JSON output, or error text.** Intake is stdin,\n  `--from-env`, or an interactive prompt only.\n- **Accepted limitation:** secret strings are not zeroized in memory (same as the Python\n  implementation). A core dump or a sufficiently privileged local process can recover them.\n\nVulnerabilities: see [SECURITY.md](SECURITY.md). Please do not open a public issue.\n\n## Origin\n\nkdbx began as a Python skill in\n[`yarrasys/extensions`](https://github.com/yarrasys/extensions/tree/main/skills/kdbx), a\nrepository now archived. This binary is the canonical kdbx and the Python skill is retired; the\ndesign spec that governs compatibility lives here, in\n[`docs/kdbx-go-standalone-design.md`](docs/kdbx-go-standalone-design.md). Vaults are standard KDBX4\n(Argon2, key-file-only), so any vault kdbx writes opens directly in `keepassxc-cli` and the\nKeePassXC desktop app; `.keepassxc.json` pointers and KeePass XML v2 key files are the\nordinary formats those tools already use.\n\nA few behaviors were chosen deliberately when porting from the original Python skill:\n\n| Area | Behavior | Why |\n|------|----------|-----|\n| `install-launcher` | **removed** | the binary is its own launcher; there is nothing left to install |\n| Failure to open a vault | **exit 3** | 3 is the documented contract for a locked/credential failure (the Python skill sometimes returned 1) |\n| Malformed `.env` on `import` (unterminated quote) | **exit 7** | silently losing a credential during an import is worse than failing loudly |\n| Child killed by a signal under `run` | `-1` → 255 | Go collapses every signal death to -1; this doesn't match the shell's `128+N`, so no portable caller depends on it. Normal exit codes pass through identically |\n\n## Bugs & feedback\n\nFound a bug or have a feature idea? Please [open an\nissue](https://github.com/yarrasys/kdbx/issues/new/choose). Include `kdbx --version`, your\nplatform, and redacted reproduction steps — **never paste a real secret, vault path, or key\nfile**; a description of the shape of the problem is enough.\n\nSecurity vulnerabilities are the one exception: report them privately through GitHub Security\nAdvisories (see [SECURITY.md](SECURITY.md)), **not** as a public issue.\n\n## Contributing\n\nStart with [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the build/test loop.\n`AGENTS.md` (symlinked as `CLAUDE.md`) carries the repository's rules — the engine boundary,\nthe secret-hygiene invariants, and the test discipline. Read it before opening a PR. CI runs\nthe suite on Linux, macOS and Windows plus `go vet`, `gofmt` and `golangci-lint`.\n\nParticipation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\nMIT — see [LICENSE](LICENSE). Dependency licenses are inventoried in [NOTICE](NOTICE); the\ndependency tree is MIT / BSD / Apache-2.0 throughout, with no copyleft component.\n",
  "bytes": 20277,
  "sha": "764d053100ff2ae43ec03701b42311f028ad700ac2f050ae1ed5b864fa375ebf",
  "repo_slug": "yarrasys/kdbx",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yarrasys_kdbx_5ab8f4f0/readme"
}