Node.js or Bun
Python 3
pykeepass installed in the Python environment used by the bridge (the project provides bun run setup:python)
The bridge defaults to .venv/bin/python3, or you can override with PYTHON_PATH

Python setup

Install pykeepass in the Python environment used by the bridge:

bun run setup:python

If you prefer manual installation:

python3 -m venv .venv && .venv/bin/pip install pykeepass

The bridge also works with a project-local virtual environment such as .venv.

Usage

import { openKeePassDatabase } from "./src/keepass";

const db = openKeePassDatabase("tests/fixtures/data.kdbx", {
	password: "123",
});

const entries = await db.listEntries();
console.log(entries);

Example

Run the example using the bundled data fixture credentials:

bun run src/example.ts

API

`openKeePassDatabase(path, options)`

Creates a database wrapper.

Options

password: KeePass master password
keyFile: optional key file path

`listEntries()`

Returns all entries in the database, with every entry field exposed by the bridge (title, username, password, url, notes, groupPath, otp when present).

`findEntries(query)`

Finds entries by partial match and returns the full entry objects.

`listGroups()`

Returns all groups, including their names and paths.

`createEntry(entry)`

Creates a new entry in the target database and persists it immediately.

Entry input

title: entry title
username: optional username
password: optional password
url: optional URL
notes: optional notes
groupPath: optional target group path

`createGroup(group)`

Creates a new group and persists it immediately.

Group input

name: group name
path: optional parent group path

`save()`

Persists the current database state.

`close()`

No-op for now.

Notes

The bridge currently launches a Python process per call.
This is simple and robust for a first version.
Errors from the Python bridge are propagated to the TypeScript API, including invalid or empty output.
A persistent Python process can be added later if needed.
Write operations currently open, modify, and save the database per command.
Bundled fixtures include tests/fixtures/data.kdbx and tests/fixtures/empty.kdbx; the companion JSON file stores the password and expected content for tests/examples.
Integration tests validate the bundled data.kdbx entry-by-entry and group-by-group against tests/fixtures/data.kdbx.json, and may skip cleanly when pykeepass is unavailable.