From 8501adfb9b8aa4f7a350775e84c6879ee76dda81 Mon Sep 17 00:00:00 2001 From: Will Mitchell Date: Mon, 26 Jan 2026 20:26:55 -0500 Subject: [PATCH] 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 --- skills/bitwarden/SKILL.md | 103 ++++++++ skills/bitwarden/references/cli-examples.md | 278 ++++++++++++++++++++ skills/bitwarden/references/get-started.md | 178 +++++++++++++ 3 files changed, 559 insertions(+) create mode 100644 skills/bitwarden/SKILL.md create mode 100644 skills/bitwarden/references/cli-examples.md create mode 100644 skills/bitwarden/references/get-started.md diff --git a/skills/bitwarden/SKILL.md b/skills/bitwarden/SKILL.md new file mode 100644 index 000000000..c793b6c1e --- /dev/null +++ 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="" + +# 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 diff --git a/skills/bitwarden/references/cli-examples.md b/skills/bitwarden/references/cli-examples.md new file mode 100644 index 000000000..e52ce25f5 --- /dev/null +++ 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 +``` + +## 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 --itemid --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 | jq '.login.password="newpassword"' | bw encode | bw edit item +``` + +## 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 +``` diff --git a/skills/bitwarden/references/get-started.md b/skills/bitwarden/references/get-started.md new file mode 100644 index 000000000..6589463ea --- /dev/null +++ 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 +```