--- name: bitwarden description: Access secrets from Bitwarden\/Vaultwarden vaults using the bw CLI. Use when retrieving passwords, API keys, credentials, secure notes, or attachments. Supports search, get, create, and modify operations. Security best practice — use organizations to limit vault access rather than exposing full personal vaults. --- # Bitwarden Access secrets from Bitwarden or self-hosted Vaultwarden. **Two CLIs available:** - `bw` — Password Manager (full vault access) - `bws` — Secrets Manager (scoped machine access) ← **Recommended for agents** ## Which to Use? | Use Case | CLI | Why | |----------|-----|-----| | Agent\/automation needs specific secrets | `bws` | Machine accounts with scoped access | | Need passwords, logins, secure notes | `bw` | Full password manager features | | Self-hosted Vaultwarden | `bw` | Secrets Manager requires cloud | --- # Secrets Manager (`bws`) — Recommended Machine accounts with access limited to specific projects\/secrets. Ideal for agents. ## Setup 1. **Install**: Download from [GitHub releases](https:\/\/github.com\/bitwarden\/sdk-sm\/releases) or `brew install bitwarden\/tap\/bws` 2. **Create machine account** in Bitwarden web vault → Secrets Manager 3. **Generate access token** for the machine account 4. **Grant access** to specific projects ## Authentication ```bash export BWS_ACCESS_TOKEN="0.xxxx-xxxx.xxxxx:xxxxx==" ``` ## Commands ### List Secrets ```bash bws secret list bws secret list # Secrets in specific project ``` ### Get Secret ```bash bws secret get bws secret get | jq -r '.value' # Value only ``` ### Create Secret ```bash bws secret create bws secret create API_KEY "sk-xxxx" 7b006643-89c1-4202-a5ca-90510f566030 ``` ### Edit Secret ```bash bws secret edit --value "new-value" bws secret edit --key "NEW_KEY" --note "Updated" ``` ### Delete Secret ```bash bws secret delete ``` ### Run with Secrets Injected Inject secrets as environment variables automatically: ```bash bws run -- 'npm run start' bws run --project-id -- '.\/my-script.sh' ``` ### List Projects ```bash bws project list ``` --- # Password Manager (`bw`) Full vault access. Use organizations\/dedicated accounts to limit scope. ## Security Best Practice **Use organizations or a dedicated account** to limit what the agent can access. Avoid giving full personal vault access. ## Setup 1. **Install**: `brew install bitwarden-cli` or `npm install -g @bitwarden\/cli` 2. **Login**: `bw login` (or `bw config server ` for self-hosted first) ## Authentication ```bash # Interactive export BW_SESSION=$(bw unlock --raw) # Non-interactive (headless) export BW_PASSWORD="master-password" export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw) ``` For self-hosted Vaultwarden: ```bash bw config server https:\/\/your-vaultwarden.com bw login ``` ## Commands ### Search Items ```bash bw list items --search "github" | jq '.[].name' bw list items --organizationid ``` ### Get Item ```bash bw get item "GitHub Token" bw get item "GitHub Token" | jq -r '.login.password' bw get password "GitHub Token" # Password only ``` ### Get Custom Fields ```bash bw get item "My Item" | jq -r '.fields[] | select(.name=="api_key") | .value' ``` ### Get Attachment ```bash bw get attachment "config.json" --itemid --output .\/config.json ``` ### Create Login ```bash bw get template item.login | jq '.name="Service" | .login.username="user" | .login.password="pass"' | bw encode | bw create item ``` ### Create Secure Note ```bash bw get template item.securenote | jq '.name="Note" | .notes="Content"' | bw encode | bw create item ``` ### Edit Item ```bash bw get item | jq '.login.password="newpass"' | bw encode | bw edit item ``` ### Delete Item ```bash bw delete item ``` ### Organizations & Collections ```bash bw list organizations bw list collections --organizationid bw list items --organizationid ``` ### Sync ```bash bw sync # Refresh local cache ``` ## Troubleshooting | Issue | Solution | |-------|----------| | "Vault is locked" | Run `bw unlock` and export `BW_SESSION` | | "Not logged in" | Run `bw login` | | Session expired | Re-run unlock command | | Item not found | Run `bw sync` first |