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
- Verify CLI installation: Run
bw --version to confirm the CLI is available
- Create a dedicated tmux session:
tmux new-session -d -s bw-session
- Attach and authenticate: Run
bw login or bw unlock inside the session
- Export session key: After unlock, export
BW_SESSION as instructed by the CLI
- 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/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
# 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:
bw config server https://your-bitwarden-server.com
Reference Documentation
