Keepassxc secrets

keepassxc-secrets — secrets from KeePassXC without leaking them

Agent-facing secrets live in a separate database, by default ~/.pass/agents.kdbx. Its master password is stored in the system keyring (Secret Service on Linux, Keychain on macOS, Credential Manager on Windows) and, on Linux, cached in the kernel keyring, so the commands run without prompting. The user's main database stays out of reach — that is what bounds the blast radius.

kpsec is a shell script (kpsec.ps1 on Windows). No runtime beyond the shell.

The one rule

Never print a secret and never call keepassxc-cli directly. Its output goes straight into the transcript. kpsec resolves values inside its own process and hands them to the child through the environment — they never touch stdout or argv.

Never:

keepassxc-cli show ... -a Password         # the value lands in the model context
some-cli --password "$(...)"               # the password is visible in /proc/*/cmdline
export TOKEN=$(...)                        # the value sticks in history and logs

Instead:

kpsec run -e TOKEN=kp://gitlab/api -- some-cli   # secret only in the child's env
kpsec check kp://gitlab/api                      # verify without revealing

kpsec run does not filter what the child prints. If a command is known to echo its credentials (debug output, verbose HTTP logs), do not run it under kpsec run in an agent session.

Reference format

kp://<group>/<entry>[#<Attribute>]

The default attribute is Password.

Commands

kpsec status                              # database, keyring backend, unlock check
kpsec ls                                  # entries, without values
kpsec check kp://gitlab/api               # OK + length and sha256 prefix
kpsec run -e TOKEN=kp://gitlab/api -- glab api /user
kpsec run --env-file .env.tpl -- docker compose up
kpsec add gitlab/api -u alice             # value typed by a human in a GUI dialog
kpsec add gitlab/api -g -L 32             # generate a random value
kpsec clip kp://gitlab/api                # clipboard for 15 seconds
kpsec lock                                # drop the cached master password

.env.tpl is a plain env file whose values are either literals or kp:// references. It is safe to commit — it holds no values:

REGISTRY_USER=deployer
REGISTRY_PASSWORD=kp://registry/deployer

Commands an agent must not run: kpsec add --stdin (the value would land in argv) and kpsec show-master. Those are for the human at the keyboard.

Adding a secret

kpsec add <group>/<entry> -u <username> --url <url>

The value is typed into a GUI dialog, so it never passes through the agent's command line. Verify with kpsec check kp://<group>/<entry>.

keepassxc-cli cannot set or filter by tags, so entries are organised by group (argocd/…, gitlab/…, registry/…) and the reference mirrors that path.

Building tools on top

kpsec doubles as a library. Sourcing it with KPSEC_LIB=1 skips the command dispatch and exposes resolve, kp, master_get and the keyring helpers, so a wrapper can resolve a secret without it passing through an intermediate stdout:

KPSEC_LIB=1 . "$HOME/.claude/skills/keepassxc-secrets/scripts/kpsec"

token=$(resolve "kp://gitlab/api")     # stays in this shell's memory
export GITLAB_TOKEN="$token"           # export, not `env VAR=… cmd` — argv is public
exec glab api /user

Troubleshooting

• kpsec status shows the keyring backend in use, the resolved keepassxc-cli and whether the database opens.
• unlock: FAILED — the stored key does not match the database. After moving the .kdbx, re-point the key with kpsec relocate <new-path>.
• Prompts need a graphical session; without one they are skipped rather than blocking. For headless runs set KPSEC_NO_GUI=1 — the commands then fail with exit code 4.
• Environment: KPSEC_DB, KPSEC_TTL, KPSEC_CONFIG, KPSEC_KEYRING (secretservice / keychain / none), KPSEC_KEEPASSXC_CLI, KPSEC_PROMPT_TIMEOUT.
• See references/security.md for the threat model, references/setup.md for installation and references/platforms.md for Linux/macOS/Windows specifics.