Skill: startupbros/bw-vault (version 1.0.0)

--- 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

path: references/cli-examples.md
content: # 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.[REDACTED_SECRET]"' | 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 [REDACTED_SECRET]

# Work account (different terminal)
export BITWARDENCLI_APPDATA_DIR=~/.bitwarden-work
bw login [REDACTED_SECRET]
```

## 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
```


path: references/get-started.md
content: # 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
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)