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
- Get Started Guide - Installation and initial setup
- CLI Examples - Common usage patterns and advanced operations
