command reference

kp2bw CLI reference

Every invocation mode, option, environment mapping, and default. Use kp2bw --help for a quick reminder; use this page for semantics.

usage and modes

One executable, several short-circuit modes

kp2bw [OPTIONS] FILE
python -m kp2bw [OPTIONS] FILE

The default mode reads FILE, unlocks Bitwarden through bw serve, then migrates entries, attachments, OTP and passkey fields, tags, expiry, and login URIs. The two invocation forms are equivalent.

Migration

kp2bw [options] FILE. Reads KeePass and writes Bitwarden.

KeePass-only report

--report-uris keepass FILE. Reads KeePass and changes nothing; no bw CLI or Bitwarden password needed.

Bitwarden-only

--report-uris bitwarden, --migrate-uris, and --strip-ids need no FILE or KeePass password.

Diagnostics

--doctor [--redact], --version, and --help print information and exit.

Choose one special mode per invocation. Among URI report, strip, and URI migration, report dispatch precedes strip, which precedes migration; relying on that precedence is discouraged.

environment

CLI value → environment → documented default

kp2bw searches upward from the current working directory for .env. A non-empty process environment value wins; an unset or empty one may be filled from the file. Explicit command options then win over environment values.

Boolean environment values accept 1/0, true/false, yes/no, y/n, or on/off, case-insensitively. Invalid values exit with status 2.

KP2BW_KEEPASS_PASSWORD=<keepass password>
KP2BW_BITWARDEN_PASSWORD=<bitwarden password>

Protect .env with filesystem permissions and never commit it. Prompting is safer on shared systems because command-line passwords can appear in shell history and process listings.

KeePass input and filters

Choose the source and included entries

`FILE`

Environment: KP2BW_KEEPASS_FILE
Default: Required for migration and KeePass URI reports

Path to a KeePass 2.x database. May be omitted only in modes that do not read KeePass.

`-k, --keepass-password PASSWORD`

Environment: KP2BW_KEEPASS_PASSWORD
Default: Prompt securely

KeePass database password. Prefer the prompt or environment over a command-line value.

`-K, --keepass-keyfile FILE`

Environment: KP2BW_KEEPASS_KEYFILE
Default: None

Key file required to open the KeePass database, when applicable.

`-t, --import-tags TAG [TAG ...]`

Environment: KP2BW_IMPORT_TAGS
Default: All non-excluded entries

Import only entries carrying a listed tag. The environment value is a comma-separated list.

`--skip-expired, --no-skip-expired`

Environment: KP2BW_SKIP_EXPIRED
Default: Off

Exclude or include expired KeePass entries.

`--include-recycle-bin, --no-include-recycle-bin`

Environment: KP2BW_INCLUDE_RECYCLE_BIN
Default: Off

Include or exclude entries under the KeePass Recycle Bin.

`--totp-pps, --no-totp-pps`

Environment: KP2BW_TOTP_PPS
Default: Off

Read Pleasant Password Server TOTPSecret/TOTPDigits/TOTPPeriod fields instead of KeePass TimeOtp-* fields. PPS secrets use Base32 and SHA-1.

Bitwarden destination and shape

Choose vault scope, hierarchy, and metadata

`-b, --bitwarden-password PASSWORD`

Environment: KP2BW_BITWARDEN_PASSWORD
Default: Prompt securely

Password used to unlock Bitwarden. Not needed for a KeePass-only URI report.

`-o, --bitwarden-org ID`

Environment: KP2BW_BITWARDEN_ORG
Default: Personal vault

Create and scope items in this organization.

`-c, --bitwarden-collection ID|auto|nested`

Environment: KP2BW_BITWARDEN_COLLECTION
Default: No collection mapping

Use one existing collection ID, 'auto' for top-level KeePass group names, or 'nested' for full group paths. Requires an organization.

`--folder, --no-folder`

Environment: KP2BW_CREATE_FOLDERS
Default: On for personal vault; off with an organization

Create personal Bitwarden folders from KeePass groups. --no-folder leaves personal items at the root unless collections apply.

`--path-to-name, --no-path-to-name`

Environment: KP2BW_PATH_TO_NAME
Default: Off

Prefix each item name with its KeePass group path.

`--path-to-name-skip N`

Environment: KP2BW_PATH_TO_NAME_SKIP
Default: 1

Skip the first N groups when building the item-name prefix. N must be an integer.

`--metadata, --no-metadata`

Environment: KP2BW_MIGRATE_METADATA
Default: On

Store tags and expiry in a readable YAML KP2BW_META custom field when present.

`--include-oversize-secrets`

Environment: KP2BW_INCLUDE_OVERSIZE_SECRETS
Default: Off

Allow oversized hidden OTP, passkey, and KeePass-protected fields to become plaintext .txt attachments. Without consent they are warned about and dropped, not exposed.

reruns and updates

Safe updates are the default

Migrated items carry a KeePass UUID in KP2BW_ID and a content signature in KP2BW_SYNC. Unchanged reruns are idempotent. By default, kp2bw updates changed source content but protects an item edited in Bitwarden after the prior run.

`--update, --no-update`

Environment: KP2BW_UPDATE
Default: On

Sync changed KeePass content and missing or changed attachments onto matched items. --no-update leaves existing content untouched; collection membership may still sync.

`--force-update`

Environment: KP2BW_FORCE_UPDATE
Default: Off

Overwrite matched items even when their KP2BW_SYNC stamp shows a later Bitwarden edit. Use only when KeePass must win.

URI matching and maintenance

Control autofill matching and inspect collisions

Additional KeePass URLs such as KP2A_URL, URL_1, and AndroidApp become Bitwarden login URIs. Quoted-exact and wildcard URLs keep their interpreted modes; --uri-match controls plain URLs.

`--uri-match MODE`

Environment: KP2BW_URI_MATCH
Default: default

Plain-URL match mode: domain, host, startswith, exact, regex, never, default, or null. default and null leave matching unset so the Bitwarden account setting applies.

`--interpret-uri-syntax, --no-interpret-uri-syntax`

Environment: KP2BW_INTERPRET_URI_SYNTAX
Default: On

Interpret KeePassXC additional URLs: double quotes mean exact and * means wildcard. Disable only that syntax handling; invalid, non-web, or unresolved values remain dropped, and Android packages remain transformed.

`--report-uris keepass|bitwarden`

Environment: KP2BW_REPORT_URIS
Default: Off

Read-only report of registrable domains containing multiple URI hosts. KeePass source needs FILE; Bitwarden source honors organization and collection scope.

`--migrate-uris`

Environment: KP2BW_MIGRATE_URIS
Default: Off

Bitwarden-only, idempotent upgrade: fold legacy KP2A_URL*/AndroidApp custom fields into login URIs, then exit. Honors URI settings and scope; confirms first.

finalization, diagnostics, and output

Utility options

`--strip-ids`

Environment: KP2BW_STRIP_IDS
Default: Off

Bitwarden-only finalization: remove KP2BW_ID and KP2BW_SYNC from in-scope migrated items, then exit. Irreversible and makes future reruns unreliable; confirms first.

`-y, --yes`

Environment: KP2BW_YES
Default: Off

Skip the bw setup prompt and confirmations for mutating Bitwarden-only modes.

`-v, --verbose`

Environment: KP2BW_VERBOSE
Default: Off

Show per-entry kp2bw detail on the console.

`-d, --debug`

Environment: KP2BW_DEBUG
Default: Off

Show debug and third-party HTTP request logs on the console.

`--doctor`

Default: Off

Print kp2bw, bw, server, installation, and .env diagnostics, then exit. Returns non-zero if bw is unusable.

`--redact`

Default: Off

With --doctor, mask the server URL and home-relative paths before sharing the report.

`-V, --version`

Default: —

Print the installed kp2bw version and exit.

`-h, --help`

Default: —

Print the concise command help and exit.

folders vs collections

Bitwarden folders are personal. Organization structure is collections.

This is the main migration trap. KeePass groups look like folders, but a Bitwarden organization does not have org folders. Shared structure in an organization is made with collections. Nested collections are names with slashes, such as Work/Servers.

KeePass group

Nested org collections

Top-level org collections

Personal folders

KeePass groupWork/Servers

Nested org collectionsWork/Servers

Top-level org collectionsWork

Personal foldersWork/Servers

KeePass groupInternet/Banking

Nested org collectionsInternet/Banking

Top-level org collectionsInternet

Personal foldersInternet/Banking

For a Vaultwarden organization migration, the usual shape is nested collections and no personal folders. That keeps shared data in the org model instead of creating a private folder tree beside it.

Want both? Pass --folder alongside -o (the planner's Also create personal folders toggle) and every item is filed into its org collection and a personal folder — the same double-filing Bitwarden's own org import does. Leave it off unless you specifically want that private copy.

Full-path collections

-c nested: KeePass Work/Servers becomes collection Work/Servers. With -o set, personal folders are already off, so no extra flag is needed.

Top-folder collections

-c auto: KeePass Work/Servers and Work/Engineering both land in collection Work.

Single collection

-c 11111111-1111-1111-1111-111111111111: every imported item lands in one existing collection.

Flat organization

-o with no collection mapping: items are created in the organization without a generated hierarchy or personal folders.

Personal folders

KeePass groups become personal Bitwarden folders. Use this only when importing into a personal vault.

Flat personal

--no-folder: items stay at the personal vault root.

safety and operational notes

Know what writes, what prompts, and where logs go

Install and configure bw; for self-hosting run bw config server URL, then log in once with bw login. kp2bw uses unlock.
--report-uris is read-only. --migrate-uris mutates matching fields. --strip-ids is irreversible.
-c always requires -o. Organization scope defaults personal folders off; explicit --folder opts into double filing.
A declined confirmation exits cleanly. An interrupted migration exits 130; partial item or attachment failures produce a non-zero exit.
A full DEBUG log is always written. Override its location with KP2BW_LOG_FILE or directory with KP2BW_LOG_DIR.
KP2BW_HTTP_TIMEOUT sets the per-request HTTP timeout in seconds. It defaults to 180; values above 3600 are clamped to 3600.

Default log directories: %LOCALAPPDATA%/kp2bw/logs on Windows, ~/Library/Logs/kp2bw on macOS, and $XDG_STATE_HOME/kp2bw/logs or ~/.local/state/kp2bw/logs elsewhere. Logs contain debug transport detail; review before sharing.

examples

Common complete commands

# Personal vault; preserve KeePass groups as personal folders
kp2bw vault.kdbx

# Organization; preserve full group paths as nested collections
kp2bw -o 00000000-0000-0000-0000-000000000000 -c nested vault.kdbx

# Organization; map only top-level groups and also create personal folders
kp2bw -o 00000000-0000-0000-0000-000000000000 -c auto --folder vault.kdbx

# Import selected tags, excluding expired and Recycle Bin entries
kp2bw -t work shared --skip-expired vault.kdbx

# Read-only URI collision reports
kp2bw --report-uris keepass vault.kdbx
kp2bw --report-uris bitwarden -o 00000000-0000-0000-0000-000000000000

# Upgrade legacy URL fields in one organization, without reading KeePass
kp2bw --migrate-uris -o 00000000-0000-0000-0000-000000000000

# Final adoption; remove migration stamps after interactive confirmation
kp2bw --strip-ids -o 00000000-0000-0000-0000-000000000000

# Shareable diagnostics
kp2bw --doctor --redact