keepass-cli

intent

automate the full lifecycle of a local KeePass database without touching a UI. create and inspect .kdbx files, manage entries (list, search, add, edit, delete, move), organize groups, and attach files. all operations print structured JSON. use this when you need to programmatically manage secrets, API keys, and credentials as part of a larger automation workflow.

inputs

environment variables (load from .env file):

• KEEPASS_DATABASE_PATH (required): absolute or relative path to your .kdbx file
• KEEPASS_DATABASE_PASSWORD (required): master password to unlock the database. never pass this as a CLI argument

cli dependencies:

• python 3.7+
• python-dotenv (loads .env)
• pykeepass (wraps the KeePass format)

setup before first call:

python -m pip install python-dotenv pykeepass
# create a .env file with KEEPASS_DATABASE_PATH and KEEPASS_DATABASE_PASSWORD
chmod 600 .env  # lock down permissions

file inputs (for certain commands):

• --database (optional): override KEEPASS_DATABASE_PATH for a single call
• --file (for add-attachment): local file to attach to an entry
• --force (optional): skip safety checks on delete-attachment if the binary is shared

selectors (mutually exclusive, pick one per entry or group):

• entries: --entry-uuid, --title, --query (substring search)
• groups: --group (path like "Services/APIs"), --parent-group, --destination-group
• attachments: --attachment-id (from list-attachments output) or --filename

procedure

1. create or inspect the database

• input: none (reads KEEPASS_DATABASE_PATH)
• step: run python keepass_cli.py create
• output: {"ok": true, "action": "create", "database": {"path": "...", "root_group": "Root"}} or {"ok": false, "error_code": "database_exists"} if file already exists
• alternative: run python keepass_cli.py create --force to overwrite an existing database
• step: run python keepass_cli.py database-info
• output: {"ok": true, "action": "database-info", "database": {"version": "...", "encryption": "...", "entry_count": N, "group_count": N}} with metadata on the open database

2. list entries

• input: optional --query (substring match on title), --group (filter by group path), --sort-by (one of: uuid, title, group, modified; default uuid)
• step: run python keepass_cli.py list-entries [--query TERM] [--group PATH] [--sort-by FIELD]
• output: {"ok": true, "action": "list-entries", "entries": [{"uuid": "...", "title": "...", "group": "...", ...}, ...]} with zero or more entries
• note: passwords and timestamps are omitted unless you pass --show-secrets or --include-metadata

3. show a single entry

• input: --entry-uuid, --title, or --query (mutually exclusive); optional --show-secrets (include password, otp), --include-metadata (include created, modified, accessed, expires)
• step: run python keepass_cli.py show-entry --title "GitHub" [--show-secrets] [--include-metadata]
• output: {"ok": true, "action": "show-entry", "entry": {"uuid": "...", "title": "...", "username": "...", "url": "...", "notes": "...", "group": "...", "attachments": [...], ...}} with all fields
• edge case: if --query matches zero entries, return {"ok": false, "error_code": "not_found"}
• edge case: if --query or --title matches two or more entries, return {"ok": false, "error_code": "ambiguous_selector"}

4. add an entry

• input: --title (required), --username (optional), --url (optional), --notes (optional), --password (required), --group (optional, defaults to root), optional --include-metadata (return created, modified, expires timestamps)
• step: run python keepass_cli.py add-entry --title "GitHub" --username "agent@example.com" --url "https://github.com" --group "Services/APIs" --password "YOUR_PASS"
• output: {"ok": true, "action": "add-entry", "entry": {...}} with the new entry details
• edge case: if an entry with the same title already exists in that group, the CLI adds it anyway (KeePass allows duplicates)
• edge case: if the group does not exist, return {"ok": false, "error_code": "not_found"}

5. edit an entry

• input: entry selector (--entry-uuid, --title, or --query), at least one field to change (--username, --url, --notes, --password), optional --include-metadata
• step: run python keepass_cli.py edit-entry --title "GitHub" --username "newuser@example.com"
• output: {"ok": true, "action": "edit-entry", "entry": {...}} with updated entry
• edge case: if you pass no fields to change, return {"ok": false, "error_code": "no_fields_provided"}
• edge case: if the entry selector is ambiguous (matches 2+ entries), return {"ok": false, "error_code": "ambiguous_selector"}

6. delete an entry

• input: entry selector (--entry-uuid, --title, --query), optional --permanent (skip recycle bin, delete immediately)
• step: run python keepass_cli.py delete-entry --title "GitHub"
• output: {"ok": true, "action": "delete-entry", "entry": {"uuid": "...", "title": "...", ...}} confirming what was deleted
• default behavior: entry lands in Recycle Bin and can be restored
• alternative: run python keepass_cli.py delete-entry --title "GitHub" --permanent to skip the bin

7. move an entry to a different group

• input: entry selector, --destination-group (required, path like "Archive")
• step: run python keepass_cli.py move-entry --title "GitHub" --destination-group "Archive"
• output: {"ok": true, "action": "move-entry", "entry": {...}} with updated group path
• edge case: if destination group does not exist, return {"ok": false, "error_code": "not_found"}

8. list groups

• input: optional --sort-by (one of: uuid, name, path, default uuid)
• step: run python keepass_cli.py list-groups [--sort-by path]
• output: {"ok": true, "action": "list-groups", "groups": [{"uuid": "...", "name": "...", "path": "...", "entry_count": N}, ...]} with all groups

9. add a group

• input: --name (required, e.g. "APIs"), --parent-group (optional, path like "Services"; defaults to root)
• step: run python keepass_cli.py add-group --name "APIs" --parent-group "Services"
• output: {"ok": true, "action": "add-group", "group": {"uuid": "...", "name": "APIs", "path": "Services/APIs", ...}}
• edge case: if parent group does not exist, return {"ok": false, "error_code": "not_found"}
• edge case: if a group with the same name already exists in that parent, KeePass allows it (check your own logic if duplicates matter)

10. delete a group

• input: --group (required, path like "Services/APIs"), optional --permanent (default: move to recycle bin)
• step: run python keepass_cli.py delete-group --group "Services/APIs"
• output: {"ok": true, "action": "delete-group", "group": {"uuid": "...", "name": "APIs", "path": "Services/APIs"}}
• edge case: if you try to delete the root group, return {"ok": false, "error_code": "root_protected"}
• edge case: if the group does not exist, return {"ok": false, "error_code": "not_found"}

11. move a group

• input: --group (source path), --destination-group (target parent path)
• step: run python keepass_cli.py move-group --group "APIs" --destination-group "Archive"
• output: {"ok": true, "action": "move-group", "group": {...}} with updated path
• edge case: if you try to move the root group, return {"ok": false, "error_code": "root_protected"}
• edge case: if you try to move a group into itself or one of its own descendants, return {"ok": false, "error_code": "invalid_move"}

12. list attachments on an entry

• input: entry selector (--entry-uuid, --title, --query)
• step: run python keepass_cli.py list-attachments --title "GitHub"
• output: {"ok": true, "action": "list-attachments", "attachments": [{"id": 0, "filename": "token.pem", "size": 1234, ...}, ...]} with all attachments on that entry

13. add an attachment to an entry

• input: entry selector, --file (path to local file, required)
• step: run python keepass_cli.py add-attachment --title "GitHub" --file ./token.pem
• output: {"ok": true, "action": "add-attachment", "attachment": {"id": 0, "filename": "token.pem", "size": 1234, ...}}
• edge case: if the file does not exist, return {"ok": false, "error_code": "file_not_found"}
• edge case: if the entry does not exist, return {"ok": false, "error_code": "not_found"}

14. delete an attachment

• input: entry selector, attachment selector (--attachment-id or --filename, mutually exclusive), optional --delete-binary (remove the underlying binary data), optional --force (override safety checks)
• step: run python keepass_cli.py delete-attachment --title "GitHub" --attachment-id 0
• output: {"ok": true, "action": "delete-attachment", "attachment": {"id": 0, "filename": "token.pem"}}
• edge case: if you pass --delete-binary and other entries still reference the same binary, return {"ok": false, "error_code": "shared_resource"} unless you also pass --force
• edge case: if the attachment does not exist, return {"ok": false, "error_code": "not_found"}

decision points

if the database file does not exist at KEEPASS_DATABASE_PATH:

• calling any command except create will return {"ok": false, "error_code": "database_not_found"}. call create first.

if KEEPASS_DATABASE_PASSWORD is missing or wrong:

• any command that reads the database returns {"ok": false, "error_code": "auth_failure"}. verify the env var is set and correct.

if KEEPASS_DATABASE_PATH or KEEPASS_DATABASE_PASSWORD is missing entirely:

• return {"ok": false, "error_code": "missing_env_var", "var": "KEEPASS_DATABASE_PATH"} or similar.

if a .kdbx file is corrupted or in an unsupported version:

• return {"ok": false, "error_code": "database_corrupt"}. you may need to restore from a backup.

if an entry or group selector is ambiguous (matches 2+ results):

• do not pick one arbitrarily. return {"ok": false, "error_code": "ambiguous_selector", "matches": N}. the caller must refine their selector.

if a selector matches zero results:

• return {"ok": false, "error_code": "not_found"}. the resource does not exist or has already been deleted.

if an argument is invalid (e.g. unknown --sort-by value):

• return {"ok": false, "error_code": "invalid_argument", "argument": "sort-by", "reason": "..."}.

if a command hits an unexpected Python exception:

• return {"ok": false, "error_code": "internal_error", "type": "ValueError", "message": "..."} with the exception class and message. log the full traceback to stderr for debugging.

if the database hits a rate limit or resource contention (concurrent writes):

• pykeepass is single-threaded and does not lock the file. if two processes write simultaneously, the second to save wins and may lose data. the skill does not prevent this, so your caller must serialize all writes to the same database file.

if network I/O is required (none by default):

• this skill operates entirely on local files. no network calls are made.

output contract

every command returns exactly one JSON object to stdout. the object has this schema:

{
  "ok": boolean,
  "action": string (e.g. "add-entry", "list-entries"),
  "entry"?: object | object[] (present on entry commands),
  "group"?: object | object[] (present on group commands),
  "attachment"?: object | object[] (present on attachment commands),
  "database"?: object (present on database commands),
  "error"?: string (human-readable, present if ok=false),
  "error_code"?: string (machine-readable, present if ok=false),
  "type"?: string (Python exception class, present if error_code="internal_error"),
  "message"?: string (exception message, present if error_code="internal_error")
}

exit status:

• 0: success (ok=true)
• 2: handled error (ok=false, predictable error code)
• 1: unexpected error (ok=false, error_code="internal_error" or crash)

error codes (stable across versions, match on these not the human-readable error string): invalid_argument, invalid_selector, not_found, ambiguous_selector, auth_failure, database_not_found, database_exists, database_corrupt, missing_env_var, root_protected, invalid_move, file_not_found, shared_resource, no_fields_provided, internal_error

secret fields (withheld by default):

• entry password and otp are omitted unless you pass --show-secrets
• entry timestamps (created, modified, accessed, expires, expiry_time) are omitted unless you pass --include-metadata

example success response:

{
  "ok": true,
  "action": "add-entry",
  "entry": {
    "uuid": "b6f1...c2",
    "title": "GitHub",
    "username": "agent@example.com",
    "url": "https://github.com",
    "notes": "",
    "group": "Services/APIs",
    "attachments": []
  }
}

example error response:

{
  "ok": false,
  "action": "show-entry",
  "error": "No entry matched the supplied selector.",
  "error_code": "not_found"
}

outcome signal

you know the skill worked when:

• exit status is 0 and the response has "ok": true and the expected action field
• the response object contains the updated or created resource (entry, group, attachment, or database info)
• for list-* commands, an array under entries, groups, or attachments (may be empty)
• for delete commands, the response echoes back what was deleted (including uuid and title) so you can log it
• if you passed --show-secrets, the response includes password and otp fields
• if you passed --include-metadata, the response includes timestamp fields like created and modified
• subsequent calls to the same database reflect your changes (new entry appears in list-entries, moved group has new path, etc.)

human-readable error strings in error are for debugging only. check error_code to decide whether to retry, escalate, or report the problem to the user. if exit status is 1, the skill encountered an unexpected state; check logs and consider this a fatal failure.