Secure automation for KeePass databases — add, get, list, and delete secrets via command line with password caching.
- ✅ add — Create entries with auto-mkdir for nested groups (creates path hierarchy automatically)
- ✅ get — Retrieve entry password/metadata (JSON output)
- ✅ get --decrypt-to-env — Export password as shell variable for automation (
evalfriendly) - ✅ list — Show groups and entries (with
--verbosefor full details) - ✅ delete — Remove entries
- ✅ login/logout — Cache master password for 2.5h (avoids repeated prompts)
- ✅ Secure — Password never printed to console, cached securely
- ✅ Zero dependencies — Uses Python stdlib + system
kpclitool
- Python 3.7+
kpcli(KeePass CLI tool)- KDBX v2.x database file
# Install kpcli (Debian/Ubuntu)
sudo apt install kpcli
# Clone this repo
git clone https://github.com/Phanfree/kdbx-cli.git
cd kdbx-cli
# Make executable
chmod +x kdbx-cli.py
# Optional: Link to PATH
sudo ln -s $(pwd)/kdbx-cli.py /usr/local/bin/kdbx-cli# Cache password (valid for 2.5 hours)
python3 kdbx-cli.py login --db mydb.kdbx --password "mypassword"
# Now subsequent commands don't need --password
python3 kdbx-cli.py list
python3 kdbx-cli.py get "services/github/token"
# Logout (clear cache immediately)
python3 kdbx-cli.py logout --db mydb.kdbx# Single operation with password inline
python3 kdbx-cli.py get "services/github/token" --db mydb.kdbx --password "mypassword"# List all groups and entries
python3 kdbx-cli.py list --db mydb.kdbx
# List with recursive entry details
python3 kdbx-cli.py list --verbose --db mydb.kdbx
# Get entry password (JSON)
python3 kdbx-cli.py get "services/github/token" --db mydb.kdbx --password "..."
# Get password as shell variable (for automation)
eval $(python3 kdbx-cli.py get "services/github/token" --decrypt-to-env GITHUB_TOKEN --password "...")
# Add new entry (creates groups if they don't exist)
python3 kdbx-cli.py add "services/github/token" "ghp_xxx" \
--username "octocat" \
--db mydb.kdbx --password "..."
# Delete entry
python3 kdbx-cli.py delete "services/github/token" --db mydb.kdbx --password "..."# Set default database path
export KDBX_DATABASE="/path/to/my.kdbx"
# Now --db is optional
python3 kdbx-cli.py list --password "..."
# Set password (NOTE: security risk, use caching instead!)
export KDBX_PASSWORD="mypassword"
# Both optional now
python3 kdbx-cli.py listAll commands return JSON (except --decrypt-to-env):
# list
{
"groups": ["accounts", "services"],
"entries": [
{
"path": "/services/github/token",
"title": "token"
}
]
}
# get (JSON)
{
"title": "token",
"username": "octocat",
"password": "ghp_xxx",
"url": "",
"notes": ""
}
# get --decrypt-to-env VAR (Shell export)
export GITHUB_TOKEN='ghp_xxx'
# add/delete (Status)
{
"status": "ok",
"path": "/services/github/token"
}
# error
{
"error": "Entry not found: services/missing/token"
}Dos:
- ✅ Use
loginto cache password for batch operations - ✅ Use
--decrypt-to-envfor automation pipelines - ✅ Let cache auto-expire (2.5h TTL)
- ✅ Store database files with restricted permissions (
chmod 600)
Don'ts:
- ❌ Never hardcode password in scripts
- ❌ Never echo passwords to console
- ❌ Never set
KDBX_PASSWORDenv var (defeats caching purpose) - ❌ Never write secrets to temporary files
# Cache password once
python3 kdbx-cli.py login --db secrets.kdbx --password "..."
# Use token for git operations
eval $(python3 kdbx-cli.py get "services/github/token" --decrypt-to-env GITHUB_TOKEN)
gh auth login --with-token < <(echo $GITHUB_TOKEN)
# Cleanup
unset GITHUB_TOKEN# Get Groq API key
eval $(python3 kdbx-cli.py get "services/groq/api-key" --decrypt-to-env GROQ_API_KEY)
# Run container with secret
docker run -e GROQ_API_KEY="$GROQ_API_KEY" myapp:latest
# Cleanup
unset GROQ_API_KEY# Create entry with username
python3 kdbx-cli.py add "services/newapi/token" "secret123" \
--username "[email protected]" \
--db secrets.kdbx --password "..."
# Verify it was added
python3 kdbx-cli.py get "services/newapi/token" --db secrets.kdbx --password "..."PTY Session Handling: The script uses separate PTY sessions for stability:
- Session 1: Create missing directory structure (groups)
- Session 2: Create entry in clean environment
This avoids terminal state corruption during interactive prompts.
Cache Storage:
- Location:
~/.cache/kdbx-cli/<db-hash>.cache - Format: Secure hash + timestamp
- TTL: 2.5 hours from last access
- Auto-cleanup: Expired caches are deleted on logout
Error Handling:
All errors return JSON with "error" key, making it easy to parse in scripts.
"Cannot unlock database"
- Wrong master password
- Corrupted KDBX file
- Verify:
file secrets.kdbxshould show "KeePass password database"
"Entry not found"
- Path is case-sensitive
- Use
listto verify exact path - Example:
services/GitHub/token≠services/github/token
"kpcli not found"
- Install:
sudo apt install kpcli - Or set:
KPCLI_PATH=/path/to/kpcli
"Permission denied" on cache
- Check:
ls -la ~/.cache/kdbx-cli/ - Fix:
chmod 700 ~/.cache/kdbx-cli/