Bitwarden CLI

Item: Bitwarden CLI
Rating: 7.3
Author: Implexa

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.

view source

installs

stars

karma

SkillRank score ↗

7.3/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-05-26

bw-vault covers bitwarden cli setup, authentication via email/password/api key/sso, and vault secret retrieval. enforces tmux session management and session key export for all operations.

structure

9.0

trigger phrases

7.0

procedure

8.0

edge cases

6.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

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

related skills

semantically similar in the cross-vendor index

clawhub

84% match

Vaultwarden Secrets

Manage Vaultwarden secrets with wrapper scripts for session handling, caching, logging, and scoped read/write operations in collections or personal vaults.

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.

Bitwarden CLI Skill

intent

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.

inputs

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)

Email/password method: Bitwarden account email and master password.
API key method: BW_CLIENTID and BW_CLIENTSECRET environment variables set before login. Obtain these from the Bitwarden web vault under Settings > Account > API Key.
SSO method: Organization identifier or SSO provider configuration. Enterprise/org accounts only.

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).
Bitwarden self-hosted server URL (if using Vaultwarden or self-hosted instance instead of Bitwarden cloud).

Edge cases to handle

Session key expiry: tokens expire after logout, lock, or manual revocation; re-authenticate if "Vault is locked" or "not logged in" errors appear.
Rate limiting: Bitwarden API may throttle rapid requests; add delays between bulk operations.
Network timeouts: connectivity issues during login/unlock will hang; set reasonable timeouts or have manual fallback ready.
Empty vault or no matching items: bw list and bw get may return no results if item doesn't exist or filters find nothing.

procedure

Verify CLI installation and environment
- Input: system $PATH
- Run bw --version to confirm the binary is available.
- Output: version string (e.g., "Bitwarden CLI 2024.1.0") or error if not installed.
- On failure: stop and guide user to install via npm, Homebrew, or Chocolatey.
Create or attach to dedicated tmux session
- Input: system tmux availability.
- Run 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.
- Output: session created or attached (tmux outputs nothing on success; check with tmux list-sessions).
- On failure (tmux not found): stop and request manual setup. Session key cannot be preserved without tmux.
Authenticate to Bitwarden vault (choose method based on inputs)
- Input: authentication method (email/password, API key, or SSO) and credentials.
- Run one of:
  - 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).
- Output: "You have successfully logged in" message or error (invalid credentials, network failure, rate limit).
- For email/password: vault is unlocked automatically; skip to step 5.
- For API key or SSO: vault remains locked after login; proceed to step 4.
Unlock vault with session key (API key and SSO logins only)
- Input: locked vault (output from step 3 if using API key or SSO).
- Run tmux send-keys -t bw-session "bw unlock --raw" Enter to retrieve the session key in raw format.
- Output: session key string (e.g., "abcd1234...") printed to stdout.
- Capture this key: run tmux capture-pane -t bw-session -p to read the output, or store the key manually from the terminal.
- Export the key: export BW_SESSION="<captured_key>" in the same tmux session.
- On failure: "Vault is locked" or "Invalid credentials" errors mean re-run login.
Execute vault read operations within the session
- Input: vault unlocked, BW_SESSION exported in tmux session, item name or ID to fetch.
- Run vault commands inside the tmux session:
  - 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.
- Output: secret value (password, username, TOTP), full JSON object, or list of items. On item not found: empty result or "Not found" error.
- Capture output: use 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
- Input: vault operations complete.
- Run tmux send-keys -t bw-session "bw lock" Enter to lock the vault and invalidate the session key.
- Run tmux send-keys -t bw-session "bw logout" Enter if fully closing the session (vault locked and credentials cleared).
- Output: confirmation message or silent success.
- Optional: kill the tmux session with tmux kill-session -t bw-session if not reusing it.
- On skip: session remains active and unlocked; only lock if finished with vault operations.

decision points

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.

output contract

Success state:

Session key is exported as BW_SESSION environment variable in the tmux session (visible via tmux send-keys -t bw-session "echo $BW_SESSION" Enter).
Vault read commands return secrets in the requested format:
- Password/username/TOTP: plain text string (no quotes).
- Full item: JSON object (valid jq input).
- List items: array of JSON objects (one per line or as full array depending on command).
No secrets are logged to stdout, terminal history, or disk unless explicitly piped to a file or command.

File locations:

Bitwarden CLI config and cache stored in ~/.config/Bitwarden CLI/ (default) or $BITWARDENCLI_APPDATA_DIR if set.
Session keys stored in memory only; not written to disk.

Data format:

Secrets retrieved via bw get are returned as strings (passwords, usernames) or JSON (full items, lists).
Pipe to jq to parse JSON fields: bw get item 'ItemName' | jq -r '.fields[] | select(.name=="api_key") | .value'.

outcome signal

User can confirm success by running echo $BW_SESSION inside the tmux session and seeing a non-empty session key string.
Vault read commands return the expected secret (e.g., password for 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.
If retrieving secrets into environment variables for downstream use, the variable is populated and non-empty: export API_KEY=$(tmux send-keys -t bw-session "bw get password 'API'" -P | tail -1) followed by echo $API_KEY shows the secret.