bitwarden

---
name: bitwarden
description: Secure credential and secret management for AI agents and users using Bitwarden CLI. Use when retrieving passwords, API keys, injecting secrets into workflows, or managing vault items. Triggers on: bitwarden, bw, password manager, secrets, vault, credentials.
license: MIT
---

# Bitwarden Secrets Skill

Secure, standards-compliant credential management for AI agents and human users using the free Bitwarden Password Manager CLI. Populate `.env` files or inject secrets at runtime without manual copy/paste.

## When to Use

- Retrieving passwords, API keys, or credentials from Bitwarden vault
- Populating `.env` files from vault secrets
- Injecting secrets into commands without writing to disk
- Managing vault items (list, get, create, update)
- Generating secure passwords
- Any task involving "bitwarden", "bw", "password manager", "secrets", "vault", "credentials"

## Prerequisites

1. **Bitwarden Account**: Free or paid, with [Personal API Key](https://vault.bitwarden.com/#/settings/security)
2. **CLI Tools**:
   ```bash
   # Install bw CLI
   snap install bitwarden                    # Linux
   brew install bitwarden                     # macOS
   npm install -g @bitwarden/cli              # Node.js
   ```
3. **jq**: JSON processor (`apt install jq` / `brew install jq`)
4. **Python 3**: For Python wrapper usage

## Installation

### Quick Install (Manual)

1. Copy the skill to your agent's skills directory:
   - Claude: `~/.claude/skills/utility/`
   - Codex: `~/.config/codex/skills/`
   - Generic: any directory in your agent's skill search path

   ```bash
   mkdir -p ~/.claude/skills/utility
   cp -r <skill-folder> ~/.claude/skills/utility/bitwarden
   ```

2. Create XDG-compliant credential file:
   ```bash
   mkdir -p ~/.config/bitwarden
   cat > ~/.config/bitwarden/credentials <<'EOF'
   export BW_CLIENTID="your-client-id"
   export BW_CLIENTSECRET="your-client-secret"
   export BW_PASSWORD="your-master-password"
   EOF
   chmod 600 ~/.config/bitwarden/credentials
   ```

3. Test the skill:
   ```bash
   cd ~/.claude/skills/utility/bitwarden
   ./scripts/bitwarden.sh status
   ```

### Git Install (Recommended)

```bash
cd ~/.claude/skills/utility
git clone <repository-url> bitwarden
cd bitwarden
# Configure credentials as above
```

## Credential File (XDG-Compliant)

Store credentials in `~/.config/bitwarden/credentials` (chmod 600):

```bash
export BW_CLIENTID="user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export BW_CLIENTSECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export BW_PASSWORD="your-vault-master-password"
# Optional for self-hosted:
export BW_SERVER_URL="https://your-bitwarden.example.com"
```

**Note**: `BW_PASSWORD` is your vault master password. The API key authenticates the CLI, but unlock still requires the master password to decrypt vault data.

## Authentication Workflow

1. **API Key Login**: Authenticates CLI session
   ```bash
   bw login --apikey --nointeraction
   ```

2. **Unlock Vault**: Decrypts vault data (requires `BW_PASSWORD`)
   ```bash
   bw unlock --passwordenv BW_PASSWORD
   ```

3. **Session Persistence**: `BW_SESSION` token cached at `~/.config/bitwarden/session.env`

## Common Operations

### CLI Basics
```bash
bw status                              # Check vault state
bw list items --search "api key"        # Search vault
bw get item "Example API Key" | jq -r '.login.password'  # Get secret
bw generate --length 32 --uppercase --number --special  # Generate password
```

### Using the Skill Script (`scripts/bitwarden.sh`)

```bash
# Direct secret retrieval
./scripts/bitwarden.sh get-secret --name "Example API Key" --field password
./scripts/bitwarden.sh get-secret --name "GitHub" --field username

# List secrets (requires search term for security)
./scripts/bitwarden.sh list-secrets --search "api"

# Full login credentials
./scripts/bitwarden.sh get-login --service "GitHub"

# Vault management
./scripts/bitwarden.sh login           # API key login
./scripts/bitwarden.sh unlock          # Unlock with BW_PASSWORD
./scripts/bitwarden.sh status          # Check status
./scripts/bitwarden.sh lock            # Lock vault
```

### Mapping File for .env Population

Create `bitwarden-env-map.json`:
```json
{
  "env_file": ".env",
  "create_backup": true,
  "write_mode": "merge",
  "secrets": [
    {
      "env": "OPENAI_API_KEY",
      "source": "item_field",
      "search": "OpenAI API Key",
      "field": "password"
    },
    {
      "env": "DB_PASSWORD",
      "source": "item_field",
      "search": "Production Database",
      "field": "password"
    }
  ]
}
```

**Write Modes**:
- `merge`: Preserve existing vars, update/add mapped secrets (default)
- `replace`: Rebuild `.env` from mapped secrets only
- `ephemeral`: Inject into command runtime, no `.env` written

### Populate .env File
```bash
./scripts/bitwarden.sh populate-env-from-map bitwarden-env-map.json
```

### Inject Secrets Into Command (No Disk Write)
```bash
./scripts/bitwarden.sh inject-env bitwarden-env-map.json -- npm start
```

### Create Template
```bash
./scripts/bitwarden.sh create-template -o bitwarden-env-map.json
```

## Python API

```python
from scripts.bitwarden_skill import BitwardenSecrets

bw = BitwardenSecrets()

# Check status
status = bw.check_status()

# Get single secret
api_key = bw.get_secret("OpenAI API Key", field="password")

# Populate .env from mapping
result = bw.populate_from_map("bitwarden-env-map.json")

# Inject and run command
result = bw.inject_env("bitwarden-env-map.json", "python app.py")

# Generate password
pwd = bw.generate_password(length=32)
```

## Security Best Practices

- Never commit `~/.config/bitwarden/credentials` to git
- Use specific item names; avoid broad searches
- Prefer `inject-env` over writing `.env` to disk
- Set `create_backup: true` to keep rollback points
- `.env` files created with 600 permissions
- Do not commit `.env` or mapping files containing real item names
- After agent runs, ensure vault is locked (`bitwarden.sh lock`)
- Store `BW_PASSWORD`, `BW_CLIENTID`, `BW_CLIENTSECRET` in a secure runner secret store

## Troubleshooting

| Error | Fix |
|-------|-----|
| `bw: command not found` | Install Bitwarden CLI: `npm install -g @bitwarden/cli` |
| `jq: command not found` | Install jq: `apt install jq` / `brew install jq` |
| `BW_CLIENTID not set` | Create `~/.config/bitwarden/credentials` with export lines |
| `Vault is locked` | Run `bw unlock --passwordenv BW_PASSWORD` |
| `Item not found` | Use `bw list items --search <term>` to find exact name |
| Session expired | Skill auto-repairs on next call via re-login |

## File Structure

```
bitwarden/
├── SKILL.md                  # This file (agentskills.io compliant)
├── scripts/
│   ├── bitwarden.sh        # Main CLI (requires bw, jq)
│   └── bitwarden_skill.py  # Python wrapper class
├── references/              # Additional documentation
├── .gitignore               # Excludes .env, sessions, mappings
└── README.md               # (optional, same as SKILL.md body)
```

## References

- [SKILL.md Specification](https://agentskills.io/specification)
- [Bitwarden CLI Docs](https://bitwarden.com/help/cli/)
- [Personal API Key Setup](https://bitwarden.com/help/personal-api-key/)