feat(skills): add Bitwarden CLI skill

Add support for Bitwarden password manager CLI (bw) with: - Email/password, API key, and SSO authentication - tmux session workflow for secure session key management - Comprehensive reference documentation - Support for self-hosted Bitwarden/Vaultwarden servers - Multiple installation methods (npm, brew, choco) Tested end-to-end on ClawdBot VM: - Skill loads as clawdbot-managed with correct metadata - bw CLI installs and authenticates successfully - Vault operations (list, get username/password) work as documented - Session key management via BW_SESSION verified Mirrors the existing 1password skill pattern for consistency. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 20:26:55 -05:00 · 2026-01-26 20:26:55 -05:00 · 8501adfb9b
commit 8501adfb9b
parent 1506d493ea
3 changed files with 559 additions and 0 deletions
--- a/skills/bitwarden/SKILL.md
+++ b/skills/bitwarden/SKILL.md
@ -0,0 +1,103 @@
+---
+name: bitwarden
+description: Set up and use Bitwarden CLI (bw). Use when installing the CLI, authenticating (login/unlock), or reading secrets from your vault. Supports email/password, API key, and SSO authentication methods.
+homepage: https://bitwarden.com/help/cli/
+metadata: {"clawdbot":{"emoji":"🔒","requires":{"bins":["bw"]},"install":[{"id":"npm","kind":"npm","package":"@bitwarden/cli","bins":["bw"],"label":"Install Bitwarden CLI (npm)"},{"id":"brew","kind":"brew","formula":"bitwarden-cli","bins":["bw"],"label":"Install Bitwarden CLI (brew)"},{"id":"choco","kind":"choco","package":"bitwarden-cli","bins":["bw"],"label":"Install Bitwarden CLI (choco)"}]}}
+---
+
+# Bitwarden CLI Skill
+
+The Bitwarden command-line interface (CLI) provides full access to your Bitwarden vault for retrieving passwords, secure notes, and other secrets programmatically.
+
+## Workflow Requirements
+
+**CRITICAL:** Always run `bw` commands inside a dedicated tmux session. The CLI requires a session key (`BW_SESSION`) for all vault operations after authentication. A tmux session preserves this environment variable across commands.
+
+### Required Workflow
+
+1. **Verify CLI installation**: Run `bw --version` to confirm the CLI is available
+2. **Create a dedicated tmux session**: `tmux new-session -d -s bw-session`
+3. **Attach and authenticate**: Run `bw login` or `bw unlock` inside the session
+4. **Export session key**: After unlock, export `BW_SESSION` as instructed by the CLI
+5. **Execute vault commands**: Use `bw get`, `bw list`, etc. within the same session
+
+### Authentication Methods
+
+| Method | Command | Use Case |
+|--------|---------|----------|
+| Email/Password | `bw login` | Interactive sessions, first-time setup |
+| API Key | `bw login --apikey` | Automation, scripts (requires separate unlock) |
+| SSO | `bw login --sso` | Enterprise/organization accounts |
+
+After `bw login` with email/password, your vault is automatically unlocked. For API key or SSO login, you must subsequently run `bw unlock` to decrypt the vault.
+
+### Session Key Management
+
+The unlock command outputs a session key. You **must** export it:
+
+```bash
+# Bash/Zsh
+export BW_SESSION="<session_key_from_unlock>"
+
+# Or capture automatically
+export BW_SESSION=$(bw unlock --raw)
+```
+
+Session keys remain valid until you run `bw lock` or `bw logout`. They do **not** persist across terminal windows—hence the tmux requirement.
+
+## Reading Secrets
+
+```bash
+# Get password by item name
+bw get password "GitHub"
+
+# Get username
+bw get username "GitHub"
+
+# Get TOTP code
+bw get totp "GitHub"
+
+# Get full item as JSON
+bw get item "GitHub"
+
+# Get specific field
+bw get item "GitHub" | jq -r '.fields[] | select(.name=="api_key") | .value'
+
+# List all items
+bw list items
+
+# Search items
+bw list items --search "github"
+```
+
+## Security Guardrails
+
+- **NEVER** expose secrets in logs, code, or command output visible to users
+- **NEVER** write secrets to disk unless absolutely necessary
+- **ALWAYS** use `bw lock` when finished with vault operations
+- **PREFER** reading secrets directly into environment variables or piping to commands
+- If you receive "Vault is locked" errors, re-authenticate with `bw unlock`
+- If you receive "You are not logged in" errors, run `bw login` first
+- Stop and request assistance if tmux is unavailable on the system
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `BW_SESSION` | Session key for vault decryption (required for all vault commands) |
+| `BW_CLIENTID` | API key client ID (for `--apikey` login) |
+| `BW_CLIENTSECRET` | API key client secret (for `--apikey` login) |
+| `BITWARDENCLI_APPDATA_DIR` | Custom config directory (enables multi-account setups) |
+
+## Self-Hosted Servers
+
+For Vaultwarden or self-hosted Bitwarden:
+
+```bash
+bw config server https://your-bitwarden-server.com
+```
+
+## Reference Documentation
+
+- [Get Started Guide](references/get-started.md) - Installation and initial setup
+- [CLI Examples](references/cli-examples.md) - Common usage patterns and advanced operations
--- a/skills/bitwarden/references/cli-examples.md
+++ b/skills/bitwarden/references/cli-examples.md
@ -0,0 +1,278 @@
+# Bitwarden CLI Examples
+
+## Prerequisites
+
+All commands assume you are:
+1. Inside a tmux session: `tmux attach -t bitwarden` or `tmux new -s bitwarden`
+2. Logged in: `bw login`
+3. Unlocked with session exported: `export BW_SESSION=$(bw unlock --raw)`
+
+## Reading Credentials
+
+### Get Password by Name
+
+```bash
+# Simple lookup (requires unique name)
+bw get password "GitHub"
+
+# If multiple items match, use item ID
+bw get password 12345678-1234-1234-1234-123456789012
+```
+
+### Get Username
+
+```bash
+bw get username "GitHub"
+```
+
+### Get TOTP Code
+
+```bash
+# Returns current 6-digit code
+bw get totp "GitHub"
+```
+
+### Get Full Item (JSON)
+
+```bash
+bw get item "GitHub"
+
+# Pretty print
+bw get item "GitHub" | jq .
+
+# Extract specific login fields
+bw get item "GitHub" | jq -r '.login.username'
+bw get item "GitHub" | jq -r '.login.password'
+bw get item "GitHub" | jq -r '.login.totp'
+```
+
+### Get Custom Fields
+
+```bash
+# List all custom fields
+bw get item "AWS Credentials" | jq '.fields'
+
+# Get specific custom field by name
+bw get item "AWS Credentials" | jq -r '.fields[] | select(.name=="access_key") | .value'
+
+# Get hidden field
+bw get item "AWS Credentials" | jq -r '.fields[] | select(.name=="secret_key") | .value'
+```
+
+### Get Secure Notes
+
+```bash
+# Get note content
+bw get notes "My Secure Note"
+
+# Full item with metadata
+bw get item "My Secure Note" | jq -r '.notes'
+```
+
+## Listing and Searching
+
+### List All Items
+
+```bash
+# All items
+bw list items
+
+# Count items
+bw list items | jq 'length'
+
+# Item names only
+bw list items | jq -r '.[].name'
+```
+
+### Search Items
+
+```bash
+# Search by name (case-insensitive)
+bw list items --search "github"
+
+# Search in specific folder
+bw list items --folderid 12345678-1234-1234-1234-123456789012 --search "api"
+
+# Items without folder
+bw list items --folderid null
+```
+
+### List Folders
+
+```bash
+bw list folders
+bw list folders | jq -r '.[].name'
+```
+
+### List Organizations
+
+```bash
+bw list organizations
+```
+
+### List Collections
+
+```bash
+bw list collections
+bw list org-collections --organizationid <org-id>
+```
+
+## Environment Variable Injection
+
+### Export to Environment
+
+```bash
+# Single credential
+export GITHUB_TOKEN=$(bw get password "GitHub Token")
+
+# Multiple credentials
+export AWS_ACCESS_KEY_ID=$(bw get item "AWS" | jq -r '.fields[] | select(.name=="access_key") | .value')
+export AWS_SECRET_ACCESS_KEY=$(bw get item "AWS" | jq -r '.fields[] | select(.name=="secret_key") | .value')
+```
+
+### Run Command with Injected Secrets
+
+```bash
+# Using shell substitution
+DATABASE_URL="postgres://user:$(bw get password 'DB Prod')@host/db" ./my-app
+
+# Using environment export
+export DATABASE_PASSWORD=$(bw get password "DB Prod")
+./my-app
+```
+
+## Vault Synchronization
+
+### Sync from Server
+
+```bash
+# Full sync
+bw sync
+
+# Force sync (ignore cache)
+bw sync --force
+```
+
+### Check Sync Status
+
+```bash
+bw status | jq '.lastSync'
+```
+
+## Account Management
+
+### Check Current Session
+
+```bash
+# Full status
+bw status
+
+# Just logged-in state
+bw status | jq -r '.status'
+
+# Current user
+bw status | jq -r '.userEmail'
+```
+
+### Lock Vault
+
+```bash
+# Lock (keeps session, requires unlock)
+bw lock
+```
+
+### Logout
+
+```bash
+# Full logout (clears all session data)
+bw logout
+```
+
+## Working with Attachments
+
+### Download Attachment
+
+```bash
+# List attachments on an item
+bw get item "SSL Certificate" | jq '.attachments'
+
+# Download by attachment ID
+bw get attachment <attachment-id> --itemid <item-id> --output ./cert.pem
+```
+
+## Advanced: Creating and Editing Items
+
+### Get Templates
+
+```bash
+# Login item template
+bw get template item
+
+# Folder template
+bw get template folder
+```
+
+### Create New Item
+
+```bash
+# Create from template
+bw get template item | jq '.name="New Item" | .login.username="user" | .login.password="pass"' | bw encode | bw create item
+```
+
+### Edit Existing Item
+
+```bash
+# Get item, modify, update
+bw get item <item-id> | jq '.login.password="newpassword"' | bw encode | bw edit item <item-id>
+```
+
+## Error Handling Patterns
+
+### Check Authentication Before Operations
+
+```bash
+# Verify unlocked state
+if [ "$(bw status | jq -r '.status')" != "unlocked" ]; then
+    echo "Vault is locked. Run: export BW_SESSION=\$(bw unlock --raw)"
+    exit 1
+fi
+```
+
+### Handle Missing Items
+
+```bash
+# Check if item exists
+if ! bw get item "GitHub" >/dev/null 2>&1; then
+    echo "Item 'GitHub' not found in vault"
+    exit 1
+fi
+```
+
+## Multi-Account Setup
+
+### Use Different Config Directories
+
+```bash
+# Personal account
+export BITWARDENCLI_APPDATA_DIR=~/.bitwarden-personal
+bw login personal@example.com
+
+# Work account (different terminal)
+export BITWARDENCLI_APPDATA_DIR=~/.bitwarden-work
+bw login work@company.com
+```
+
+## Self-Hosted / Vaultwarden
+
+### Configure Custom Server
+
+```bash
+# Set server URL
+bw config server https://vault.example.com
+
+# Verify configuration
+bw config server
+
+# Reset to default Bitwarden cloud
+bw config server https://vault.bitwarden.com
+```
--- a/skills/bitwarden/references/get-started.md
+++ b/skills/bitwarden/references/get-started.md
@ -0,0 +1,178 @@
+# Bitwarden CLI: Getting Started
+
+## System Requirements
+
+The Bitwarden CLI runs on:
+- **macOS**: x64 and ARM64
+- **Windows**: x64
+- **Linux**: x64 (glibc-based distributions)
+
+For npm installation, Node.js 16+ is required.
+
+## Installation Methods
+
+### NPM (Recommended - Cross-Platform)
+
+```bash
+npm install -g @bitwarden/cli
+```
+
+This method provides automatic updates via `npm update -g @bitwarden/cli`.
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew install bitwarden-cli
+```
+
+### Chocolatey (Windows)
+
+```powershell
+choco install bitwarden-cli
+```
+
+### Snap (Linux)
+
+```bash
+sudo snap install bw
+```
+
+### Native Executables
+
+Download pre-built binaries from https://bitwarden.com/download/
+
+For Linux/macOS, grant execute permissions:
+```bash
+chmod +x bw
+sudo mv bw /usr/local/bin/
+```
+
+## Verify Installation
+
+```bash
+bw --version
+```
+
+Expected output: Version number like `2024.12.0`
+
+## Initial Configuration
+
+### Connect to Bitwarden Server
+
+For standard Bitwarden cloud (default):
+```bash
+# No configuration needed - uses https://vault.bitwarden.com by default
+```
+
+For self-hosted Bitwarden or Vaultwarden:
+```bash
+bw config server https://your-server.example.com
+```
+
+Verify server configuration:
+```bash
+bw config server
+```
+
+### First-Time Login
+
+**Interactive login (recommended for first setup):**
+```bash
+bw login
+```
+
+You'll be prompted for:
+1. Email address
+2. Master password
+3. Two-step verification code (if enabled)
+
+**Login with API key (for automation):**
+
+First, obtain your API key from the Bitwarden web vault:
+1. Go to Settings > Security > Keys
+2. View API Key
+3. Note your `client_id` and `client_secret`
+
+```bash
+# Set environment variables
+export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+export BW_CLIENTSECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+
+# Login
+bw login --apikey
+
+# Unlock vault (required after API key login)
+export BW_SESSION=$(bw unlock --raw)
+```
+
+### Session Management with tmux
+
+The CLI requires a session key for vault operations. Use tmux to preserve sessions:
+
+```bash
+# Create a dedicated session
+tmux new-session -d -s bitwarden
+
+# Attach to session
+tmux attach -t bitwarden
+
+# Inside tmux: login and export session
+bw login
+export BW_SESSION=$(bw unlock --raw)
+
+# Now run your commands
+bw list items
+
+# When finished
+bw lock
+
+# Detach from tmux (Ctrl+B, then D)
+```
+
+## Verify Access
+
+After login and unlock:
+
+```bash
+# Check authentication status
+bw status
+
+# List vaults (should show your email)
+bw list organizations
+
+# Sync vault data
+bw sync
+```
+
+## Troubleshooting
+
+### "You are not logged in"
+
+Run `bw login` to authenticate.
+
+### "Vault is locked"
+
+Run `bw unlock` and export the session key:
+```bash
+export BW_SESSION=$(bw unlock --raw)
+```
+
+### "Session key is invalid"
+
+The session has expired. Re-unlock:
+```bash
+bw lock
+export BW_SESSION=$(bw unlock --raw)
+```
+
+### Command hangs or times out
+
+Check network connectivity to Bitwarden server:
+```bash
+curl -I https://vault.bitwarden.com
+```
+
+For self-hosted servers, verify the server URL:
+```bash
+bw config server
+```