bcup2kdbx

Convert a Buttercup vault (.bcup) into a KDBX 4 database you can open in KeePassXC, KeePass 2, KeeWeb, Strongbox, or anything else that reads KeePass files.

Groups, custom fields, attachments, tags, OTP secrets and the trash all come across. The tool re-reads the file it just wrote and proves nothing was dropped before it exits.

$ bcup2kdbx ~/Buttercup.bcup ~/Buttercup.kdbx
Master password for /Users/you/Buttercup.bcup:
New password for /Users/you/Buttercup.kdbx:
Confirm password:
Unlocking vault...
Read 14 group(s), 231 entry/entries.
Converting...
Wrote /Users/you/Buttercup.kdbx (271104 bytes, KDBX 4, Argon2id).
Verifying...
Verified: every group, property value and attachment round-tripped.

npm install -g @dizitart/bcup2kdbx

Or run it once without installing:

npx @dizitart/bcup2kdbx vault.bcup vault.kdbx

Requires Node 20 or later.

bcup2kdbx <input.bcup> <output.kdbx> [options]

It prompts for the vault's master password, then twice for the password that will protect the new KDBX file. Passwords are never read from command-line arguments or environment variables, so they cannot leak into your shell history or into ps output.

Exit codes: 0 success, 1 error, 2 verification found missing data.

In the Buttercup desktop app the vault file on disk is the .bcup — for a local vault it is the file you chose when you created it. For a cloud vault (Dropbox, Google Drive, WebDAV), download the .bcup from that service first.

Open the result in your KeePass client and spot-check a handful of entries before you delete anything. The verification pass proves the data is in the file; it cannot prove your particular client displays it the way you expect.

Credit-card entries follow Buttercup's own layout: the card holder is username and the card number is password, so they land in UserName and Password.

If a custom field collides with a slot already taken — an entry with both title and Title, say — the canonical lower-case property wins the standard KDBX field and the other is kept alongside it as Title (2). Nothing is silently dropped.

Entry history. Buttercup stores a field-level changelog, not entry snapshots. Reconstructing KDBX history entries from it would fabricate "previous versions" that never existed, so only current values are written.

Entry timestamps. Buttercup stores none of its own. Creation and modification times are derived from the earliest and latest entry in that changelog — the best answer available, but derived rather than recorded.

If a field value contains a tab or a \r\n line ending, the converter prints a note during verification. The characters are written to the KDBX file intact — kdbxweb's serialiser emits them verbatim — but kdbxweb's own XML reader drops tabs when it loads the file back, so the verification pass can only match those values after normalising. Whether a tab survives into your KeePass client depends on that client's XML parser; a spec-compliant parser keeps tabs in element content and collapses \r\n to \n.

This affects display only. Nothing is dropped from the file that is written.

Reading is done by buttercup — Buttercup's own vault stack, so decryption, format handling and attachment decryption are exactly what the Buttercup app does. Writing is kdbxweb. Neither format is parsed or serialised by hand anywhere in this repository.

kdbxweb ships no Argon2 implementation, so hash-wasm supplies one. Output is KDBX 4 with Argon2id key derivation.

Everything runs locally. There is no network access at runtime and no telemetry.

import { openVault, vaultToKdbx } from "@dizitart/bcup2kdbx";
import { writeFileSync } from "node:fs";

const source = await openVault("vault.bcup", vaultPassword);
const db = await vaultToKdbx(source, newPassword, { name: "My Vault" });
writeFileSync("vault.kdbx", Buffer.from(await db.save()));
await source.lock();

vaultToKdbx returns a kdbxweb Kdbx instance, so you can modify it further before saving.

After writing, the converter reloads the file from disk and checks that every group, every property value and every attachment from the source vault is present in the output. If anything is missing it lists what and exits 2.

npm test runs an end-to-end self-check against a synthetic vault covering nested groups, all five entry types, OTP fields, attachments, field-name collisions and trashed entries.

See CONTRIBUTING.md. Bug reports are welcome — please build a synthetic vault to demonstrate the problem rather than sending anything real.

Security problems go through private reporting, never a public issue.

Apache License 2.0. Copyright 2026 Dizitart.