back
loading skill details...
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.
---
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
don't have the plugin yet? install it then click "run inline in claude" again.
restructured into six required components, added explicit decision logic for authentication methods and error states, documented all inputs and edge cases, clarified tmux session workflow and session key management, expanded output contract and outcome signals.
Use Bitwarden CLI (bw) to securely retrieve passwords, API keys, secure notes, and other vault secrets from the command line. Run this skill when you need to authenticate to your vault, manage session keys, or programmatically fetch credentials for automation, scripts, or manual secret lookups. Supports email/password, API key, and SSO login methods. Bitwarden vault operations require an active session key that must be managed carefully across commands.
Required
bw binary installed on the system (check with bw --version). Install via npm (@bitwarden/cli), Homebrew (bitwarden-cli), or Chocolatey (bitwarden-cli).tmux binary available on the system (session key persistence requires a dedicated tmux session; will fail if tmux is unavailable).Authentication credentials (pick one)
BW_CLIENTID and BW_CLIENTSECRET environment variables set before login. Obtain these from the Bitwarden web vault under Settings > Account > API Key.Optional
BW_SESSION: Pre-existing session key (if already authenticated in another session; will skip login/unlock steps).BITWARDENCLI_APPDATA_DIR: Custom config directory path (enables multi-account setups or non-default locations).Edge cases to handle
bw list and bw get may return no results if item doesn't exist or filters find nothing.Verify CLI installation and environment
$PATHbw --version to confirm the binary is available.Create or attach to dedicated tmux session
tmux new-session -d -s bw-session to create a new detached session named "bw-session", or tmux attach-session -t bw-session if it already exists.tmux list-sessions).Authenticate to Bitwarden vault (choose method based on inputs)
tmux send-keys -t bw-session "bw login" Enter for interactive email/password login.tmux send-keys -t bw-session "bw login --apikey" Enter if BW_CLIENTID and BW_CLIENTSECRET are set.tmux send-keys -t bw-session "bw login --sso" Enter for SSO (org accounts).Unlock vault with session key (API key and SSO logins only)
tmux send-keys -t bw-session "bw unlock --raw" Enter to retrieve the session key in raw format.tmux capture-pane -t bw-session -p to read the output, or store the key manually from the terminal.export BW_SESSION="<captured_key>" in the same tmux session.Execute vault read operations within the session
BW_SESSION exported in tmux session, item name or ID to fetch.tmux send-keys -t bw-session "bw get password 'ItemName'" Enter to retrieve a password by item name.tmux send-keys -t bw-session "bw get username 'ItemName'" Enter for username.tmux send-keys -t bw-session "bw get totp 'ItemName'" Enter for TOTP code.tmux send-keys -t bw-session "bw get item 'ItemName'" Enter for full item as JSON.tmux send-keys -t bw-session "bw list items" Enter to list all vault items.tmux send-keys -t bw-session "bw list items --search 'keyword'" Enter to search items by name or note content.tmux capture-pane -t bw-session -p -S -30 to grab recent terminal output (adjust -S -30 for line count).Lock vault and clean up session
tmux send-keys -t bw-session "bw lock" Enter to lock the vault and invalidate the session key.tmux send-keys -t bw-session "bw logout" Enter if fully closing the session (vault locked and credentials cleared).tmux kill-session -t bw-session if not reusing it.If no authentication method is provided: stop and ask user to supply email/password, API key credentials, or SSO details. Cannot proceed without authentication.
If BW_SESSION is already exported: skip steps 3 and 4 (login/unlock). Go directly to step 5 (vault read operations). Only re-authenticate if session is expired ("Vault is locked" or "not logged in" errors).
If API key or SSO login is used instead of email/password: step 3 will not unlock the vault automatically. Must run step 4 (bw unlock --raw) and export the session key before vault reads work.
If tmux is not available on the system: stop immediately after step 1. Session keys cannot be managed safely without tmux. Manual workaround: use bw login interactively (email/password only) and run vault commands in the same shell window without closing it. This is fragile and not recommended for scripts.
If vault search or item fetch returns empty results: item does not exist in the vault or does not match the search filter. Double-check item name spelling, try bw list items without filters to enumerate all items, or re-authenticate if vault contents changed.
If "Vault is locked" error occurs: unlock with bw unlock --raw, capture the key, and re-export BW_SESSION in the tmux session. Errors mean session key was invalidated (timeout, explicit lock, or logout).
If "You are not logged in" error occurs: user must re-run bw login (or bw login --apikey / bw login --sso). Previous session has been cleared.
If using self-hosted Bitwarden or Vaultwarden: before login, run bw config server https://your-bitwarden-server.com inside the tmux session to point the CLI to the custom server URL. Failure to do so will try to reach the public Bitwarden cloud.
Success state:
BW_SESSION environment variable in the tmux session (visible via tmux send-keys -t bw-session "echo $BW_SESSION" Enter).File locations:
~/.config/Bitwarden CLI/ (default) or $BITWARDENCLI_APPDATA_DIR if set.Data format:
bw get are returned as strings (passwords, usernames) or JSON (full items, lists).jq to parse JSON fields: bw get item 'ItemName' | jq -r '.fields[] | select(.name=="api_key") | .value'.echo $BW_SESSION inside the tmux session and seeing a non-empty session key string.bw get password 'GitHub') without errors.bw lock silently succeeds; subsequent bw get or bw list commands fail with "Vault is locked" until re-unlocked.export API_KEY=$(tmux send-keys -t bw-session "bw get password 'API'" -P | tail -1) followed by echo $API_KEY shows the secret.