bw-exporter

bw-exporter is a utility script designed to leverage the Bitwarden CLI (bw) to export specific items from your Bitwarden vault based on a Collection or a Folder.

Standard Bitwarden exports are often "all-or-nothing". This tool allows for more granular exports, producing a JSON file compatible with Bitwarden's import functionality.

Prerequisites

• Bitwarden CLI (bw): Ensure you have the Bitwarden CLI installed and available in your system's PATH.
  • Installation Instructions
• Python 3: This script is written in Python.
• Logged In & Unlocked: You must be logged into the Bitwarden CLI and your vault must be unlocked.

Handling the Session Key

When you run bw unlock, it will provide you with a session key. You must set this as an environment variable for the script to work:

# Unlock your vault
bw unlock

# Copy the export command provided by the output, e.g.:
export BW_SESSION="your_session_key_here"

Usage

The script bw_export.py has two main modes: export and stats.

Syntax

python3 bw_export.py [OPTIONS] <command> [COMMAND_OPTIONS]

Global Options

• --sync: Synchronize the local vault with the Bitwarden server before running the command. Useful if you've made changes in the web vault recently.

Commands

1. Export

Export items from a specific folder or collection.

python3 bw_export.py export --type <folder|collection> --name "<NAME>" --output <filename.json>

Options:

• --type: Specify the type of container to export from. Choices: folder, collection. (Required)
• --name: The exact name of the folder or collection to export. (Required)
• --output: The output filename (e.g., export.json). Defaults to bw_export.json.

2. Stats

View a summary of how many items are in each Folder and Collection.

python3 bw_export.py stats

Examples

Export a Folder named "Social Media":

python3 bw_export.py export --type folder --name "Social Media" --output social_media_backup.json

Export a Collection named "Developers":

python3 bw_export.py export --type collection --name "Developers" --output dev_collection.json

View Vault Statistics:

python3 bw_export.py stats

Output Format

The output is a JSON file containing an array of Bitwarden item objects. This format is generally compatible with the "Bitwarden (JSON)" import option in the Bitwarden Web Vault or Desktop App.

CSV Import Helper

A separate tool bw_csv_tool.py is provided to help import credentials from a simple CSV file (description;username;password). It can automatically infer the login URI using Google Search.

Setup

It is recommended to use a virtual environment to avoid conflicts with system packages:

# Create a virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install requirements
pip install -r requirements.txt

Usage

The import process is divided into two steps to allow for manual review.

Step 1: Create Draft (Inference)

Reads your raw CSV, searches for login pages, and creates a "draft" CSV.

Input CSV Format: description;username;password (no header)

python3 bw_csv_tool.py draft --input my_passwords.csv --output review.csv

The script will attempt to find the login page for each description. This may take some time.

Step 2: Review & Finalize

1. Open review.csv.
2. Check the name and inferred login_uri. Correct any mistakes.
3. Convert the reviewed file to Bitwarden JSON:

python3 bw_csv_tool.py convert --input review.csv --output bitwarden_import.json

4. Import bitwarden_import.json into Bitwarden using the "Bitwarden (JSON)" format.