vaultio 0.2.1

Unofficial tool for stateless Bitwarden vault management

Unofficial Python API for Bitwarden Vault Management

Overview

vaultio is an unofficial Python API for managing Bitwarden vaults via the Bitwarden CLI. Instead of launching a new CLI process for each operation, it runs the CLI once in the background and communicates with it through a private socket connection. This improves performance and provides a secure method for using the serve API to build tools and scripts.

How It Works

The API is built around the stateful Express web server launched by the bw serve command. This server exposes a local REST API for performing vault actions. vaultio wraps this API internally and delegates all actions to the Bitwarden CLI.

Note: vaultio does not cache or store credentials. All requests are proxied directly to the background process.

---

Installation

📦 Pip

pip install vaultio

🔧 Repo

cd python
python -m venv .venv
source .venv/bin/activate
pip install poetry
poetry install

---

Installing the Bitwarden CLI

Option 1: Official CLI

By default, bw serve exposes its API via HTTP over TCP, which can be less secure since other users or apps might access the unlocked vault without proper firewall rules.

You can either:

• Ensure bw is available in your PATH, or
• Run:

vaultio build

This installs the CLI from the official NPM package @bitwarden/cli.

Option 2: Unofficial Fork with Socket Support

I made a pull request that introduces support for Unix sockets and other socket types in bw serve. This allows communication without traversing the network stack, improving security.

To enable this:

• Manually build from the fork: Game4Move78/vaults#vaultio and copy the binary to:

$HOME/.cache/vaultio/bin/bw

• Or, let vaultio handle it for you:

vaultio --unofficial

This will clone the repo and build it locally. Then it will show you a diff against the official repo before prompting you to continue.

---

Usage

📘 API Documentation

See the full API reference.

📟 CLI Wrapper

vaultio --help

🧪 Example: Check Status and List Items

from vaultio.vault import Vault

with Vault() as vault:
    print(vault.status())
    print(vault.unlock())
    print(vault.status())

    for item in vault.list():
        print(item["name"])

    for folder in vault.list(type="folder"):
        print(folder["name"])

🔍 More Examples

• Creating a CLI
• Creating a shell
• Backing up vault to Unix pass

---

🔐 HTTPS Support

Not currently supported directly, but it's possible using Caddy.

Acknowledgements

• BitwardenDecrypt for the code to decrypt a vault and derive keys
• rbw for the API calls

Related

• PyWarden is a Python Bitwarden CLI wrapper

Disclaimer

This project is not associated with https://bitwarden.com/ or Bitwarden, Inc. These contributions are independent of Bitwarden and are reviewed by other maintainers.

Please note: We cannot be held liable for any data loss that may occur while using vaultio. This includes passwords, attachments, and other information handled by the application. We highly recommend performing regular backups of your files and database. However, should you experience data loss, we encourage you to contact us immediately.