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
compatibility	Requires Bitwarden CLI (bw); Linux/macOS/Windows.
allowed-tools	bash jq bw python3
metadata	{"version":"2.0.0","author":"cbwinslow","tags":"passwords, secrets, credentials, vault, cli, bitwarden","source":"https://github.com/bitwarden","docs":"https://bitwarden.com/help/cli/"}

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
2. CLI Tools:

   # 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

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

2. Create XDG-compliant credential file:

   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:

   cd ~/.claude/skills/utility/bitwarden
   ./scripts/bitwarden.sh status
   

Git Install (Recommended)

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

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

   bw login --apikey --nointeraction
   

2. Unlock Vault: Decrypts vault data (requires BW_PASSWORD)

   bw unlock --passwordenv BW_PASSWORD
   

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

Common Operations

CLI Basics

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)

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

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

./scripts/bitwarden.sh populate-env-from-map bitwarden-env-map.json

Inject Secrets Into Command (No Disk Write)

./scripts/bitwarden.sh inject-env bitwarden-env-map.json -- npm start

Create Template

./scripts/bitwarden.sh create-template -o bitwarden-env-map.json

Python API

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
• Bitwarden CLI Docs
• Personal API Key Setup