bitwarden-py 0.3.0

A simple Python wrapper for the Bitwarden CLI — programmatically read and update passwords stored in your Bitwarden vault.

bitwarden-py

A simple Python wrapper for the Bitwarden CLI — programmatically read and update passwords stored in your Bitwarden vault.

---

Requirements

Bitwarden CLI

bitwarden-py calls the official bw binary under the hood, so you must have it installed and available in your PATH.

Install it by following the official guide:
👉 https://bitwarden.com/help/cli/#download-and-install

Quick install options:

# macOS (Homebrew)
brew install bitwarden-cli

# Windows (Chocolatey)
choco install bitwarden-cli

# npm (cross-platform)
npm install -g @bitwarden/cli

After installation, verify it works:

bw --version

---

Installation

pip install bitwarden-py

Or with uv:

uv add bitwarden-py

---

Quick Start

from bitwarden_py import Bitwarden

bw = Bitwarden(
    email="[e-mail]",
    password="your_master_password",
)

# Fetch a password by item name
db_password = bw.get_password("My Database")
print(db_password)  # → "s3cr3t!"

# Update the password of an item
bw.set_password("My Database", "n3wp4ssw0rd")

Using a self-hosted server

By default the library points to https://vault.bitwarden.eu.
Pass server_url to connect to a different instance:

bw = Bitwarden(
    email="[e-mail]",
    password="your_master_password",
    server_url="https://bitwarden.yourcompany.com",
)

---

API Reference

For the full Bitwarden CLI documentation, see 👉 https://bitwarden.com/help/cli/

Bitwarden(email, password, server_url?)

Creates a new client and authenticates with the vault.

Parameter	Type	Default	Description
email	str	—	Your Bitwarden account email
password	str	—	Your master password
server_url	str	"https://vault.bitwarden.eu"	Bitwarden server URL

---

Create

bw.create_item(item) → dict

Creates a new vault item. Use bw.get_template("item") to obtain the base structure.

template = bw.get_template("item")
template["name"] = "My Login"
template["login"]["username"] = "[e-mail]"
template["login"]["password"] = "s3cr3t"
new_item = bw.create_item(template)

bw.create_folder(folder) → dict

Creates a new folder. Use bw.get_template("folder") to obtain the base structure.

template = bw.get_template("folder")
template["name"] = "Work"
new_folder = bw.create_folder(template)

bw.create_attachment(file_path, item_id) → dict

Attaches a file to an existing vault item.

bw.create_attachment("./secret.txt", "16b15b89-65b3-4639-ad2a-95052a6d8f66")

---

Read

bw.get_password(item_name) → str

Returns the password of the vault item matching item_name.

bw.get_item(id_or_name) → dict

Returns the full vault item object matching the given ID or name.

bw.get_username(id_or_name) → str

Returns the username of the vault item matching the given ID or name.

bw.get_notes(id_or_name) → str

Returns the notes of the vault item matching the given ID or name.

bw.get_uri(id_or_name) → str

Returns the URI of the vault item matching the given ID or name.

bw.get_totp(id_or_name) → str

Returns the current TOTP code for the vault item matching the given ID or name.

bw.get_template(object_type) → dict

Returns the JSON template for the given object type. Useful for constructing objects to pass to create_* and edit_* methods.

Supported types: item, item.field, item.login, item.login.uri, item.card, item.identity, item.securenote, folder, collection, item-collections, org-collection.

bw.list_items(search?, folder_id?, collection_id?, organization_id?, url?, trash?) → list[dict]

Returns a list of vault items. All parameters are optional and act as filters.

Parameter	Type	Description
search	str	Filter by search term
folder_id	str	Filter by folder ID (null / notnull)
collection_id	str	Filter by collection ID
organization_id	str	Filter by organization ID
url	str	Filter by URI
trash	bool	If True, list items in the trash

bw.list_folders(search?) → list[dict]

Returns a list of folders, optionally filtered by search.

bw.list_collections(organization_id?, search?) → list[dict]

Returns a list of collections, optionally filtered by organization ID or search term.

bw.list_organizations(search?) → list[dict]

Returns a list of organizations, optionally filtered by search.

---

Edit

bw.edit_password(item_name, new_password) → None

Updates the password of the vault item matching item_name.

bw.edit_item(item_id, item) → dict

Replaces a vault item with the provided dict. Fetch the current item with get_item first, modify it, then pass it here.

item = bw.get_item("7ac9cae8-5067-4faf-b6ab-acfd00e2c328")
item["login"]["password"] = "newp@ssw0rd"
bw.edit_item(item["id"], item)

bw.edit_folder(folder_id, folder) → dict

Replaces a folder with the provided dict.

---

Delete

bw.delete_item(item_id, permanent?) → None

Sends an item to the trash. Pass permanent=True to delete it immediately without going through trash.

bw.delete_folder(folder_id, permanent?) → None

Deletes a folder. Pass permanent=True to skip trash.

bw.delete_attachment(attachment_id, item_id) → None

Deletes an attachment from a vault item.

---

Session

bw.logout() → None

Logs out of the Bitwarden vault and clears the local session.

bw.sync() → None

Downloads the encrypted vault from the Bitwarden server. Useful when you have made changes in another Bitwarden client (web vault, browser extension, mobile app) and want the CLI to reflect the latest state.

---

License

MIT