Manage Vaultwarden secrets with wrapper scripts for session handling, caching, logging, and scoped read/write operations in collections or personal vaults.
# Vaultwarden Skill Manage secrets in Vaultwarden via wrapper scripts. All scripts handle session state, caching, logging, and error handling — do not call `bw` directly. ## CLI Version Requirement — CRITICAL Bitwarden CLI 2024.x+ breaks Vaultwarden authentication with `User Decryption Options are required`. ```bash # Install the required version npm install -g @bitwarden/cli@2023.10.0 # Verify bw --version # must show 2023.10.0 ``` `vw-unlock.sh` will hard-exit if an incompatible version is detected. ## Setup (run once) ```bash bw config server https://vaultwarden.mbojer.dk ``` ## Required Environment Variables Set in OpenClaw config, never stored in vault: | Variable | Purpose | |---|---| | `BW_CLIENTID` | API key client ID | | `BW_CLIENTSECRET` | API key client secret | | `BW_PASSWORD` | Master password for unlock | | `VW_COLLECTION_NAME` | Collection name to scope to (default: `openclaw`) — org accounts only | | `VW_COLLECTION_ID` | Hardcode collection ID — use if name lookup fails (org accounts only) | | `VW_SESSION_DIR` | Session token dir (default: `/run/openclaw/vw`) | | `VW_LOG_FILE` | Audit log path (default: `/var/log/openclaw/vaultwarden.log`) | | `VW_CACHE_TTL` | Read cache TTL in seconds (default: `60`, set `0` to disable) | ## Collection Scoping — Personal vs Org Vaults Personal Vaultwarden accounts cannot access collections via API key — this is a Bitwarden limitation, not a bug in this skill. `bw list collections` returns `[]` on personal vaults. The skill handles this automatically: if no collection is found, all operations fall back to unscoped (full vault) queries. For org accounts, set `VW_COLLECTION_NAME` or `VW_COLLECTION_ID` to scope operations to a specific collection. ## Session Management ```bash vw-unlock.sh # authenticate and unlock — run before any vault operation vw-lock.sh # lock vault and clear all caches vw-status.sh # check connection and session state vw-sync.sh # sync local cache with server — run if vault modified externally ``` Session token stored in `$VW_SESSION_DIR/.bw_session` (chmod 600). Collection ID cached in `$VW_SESSION_DIR/.collection_id` — invalidated on lock and sync. Read cache stored in `$VW_SESSION_DIR/cache/` — TTL controlled by `VW_CACHE_TTL`. ## Read Operations All reads are collection-scoped to `$VW_COLLECTION_NAME`. Frequently-read items are cached with a TTL to reduce API calls. ```bash vw-list.sh [query] # list items in openclaw collection, optional search vw-get.sh <name|id> # full item JSON vw-get-pass.sh <n> # password only (collection-scoped, cached) vw-get-user.sh <n> # username only (collection-scoped, cached) vw-get-field.sh <n> <field> # single custom field value vw-get-totp.sh <n> # current TOTP code (not cached — codes expire) ``` ## Write Operations Write operations invalidate the read cache automatically. ```bash echo <pass> | vw-create-login.sh <n> <user> # create login item (password via stdin) echo <content> | vw-create-note.sh <n> # create secure note (content via stdin) echo <value> | vw-update.sh <id> <field> # update field: password|username|notes|custom:<n> vw-delete.sh <id> <expected name> # move to trash — requires both ID and name to match vw-rotate-pass.sh <name|id> [length] # generate new password and update atomically ``` Capture rotated password cleanly (status goes to stderr): ```bash NEW_PASS=$(vw-rotate-pass.sh "MyService") ``` ## Rules - Always run `vw-unlock.sh` before vault operations, `vw-lock.sh` when done - Run `vw-sync.sh` before reads if vault was modified via web UI or another client - Always use item ID (not name) for `vw-update.sh` and `vw-delete.sh` - `vw-delete.sh` moves items to trash — not permanent. Empty trash via web UI if needed - All secret values must be passed via stdin — never as CLI arguments - Never log or output raw secret values — only names, IDs, and operation results - If any script exits non-zero, stop and report — do not retry silently - All operations are scoped to `$VW_COLLECTION_NAME` when a collection is available. Personal vaults (no org) fallback to full vault — no collection required ## Error Reference | Error | Fix | |---|---| | `bw CLI X.X.X is incompatible` | `npm install -g @bitwarden/cli@2023.10.0` | | `User Decryption Options are required` | Same as above — wrong CLI version | | `no active session` | Run `vw-unlock.sh` | | `session invalid or expired` | Run `vw-unlock.sh` | | `collection not found` | Check `VW_COLLECTION_NAME`, run `vw-sync.sh` | | `name mismatch` | Verify item ID with `vw-get.sh` before deleting | | `custom field does not exist` | Check field name with `vw-get.sh` | | `server not configured` | Run `bw config server https://vaultwarden.mbojer.dk` | | `API key login failed` | Check `BW_CLIENTID` and `BW_CLIENTSECRET` |
don't have the plugin yet? install it then click "run inline in claude" again.