bitwarden-cli

name	bitwarden-cli
description	Use when storing, retrieving, listing, or organizing secrets in Bitwarden using the bw CLI. Triggers on: "store a secret", "get the password for", "save credentials", "list vault items", "create a folder in Bitwarden", "read from Bitwarden", "load API key from vault".

bitwarden-cli

Non-interactive vault access via official bw CLI. All ops need an unlocked BW_SESSION.

Install (bw not found)

Do NOT use npm — @bitwarden/cli npm package was backdoored April 2026 (TeamPCP supply chain attack). Use the official GitHub binary:

VERSION="2026.4.2"  # check https://github.com/bitwarden/clients/releases for latest
curl -Lo /tmp/bw.zip "https://github.com/bitwarden/clients/releases/download/cli-v${VERSION}/bw-linux-${VERSION}.zip"
unzip /tmp/bw.zip -d /tmp/bw-bin && sudo mv /tmp/bw-bin/bw /usr/local/bin/bw && chmod +x /usr/local/bin/bw
bw --version

Sign up (one-time, browser)

No account yet → use chrome-devtools or any browser:

1. Navigate https://vault.bitwarden.com/#/signup, enter email, submit
2. Click "Verify Your Email" link in inbox
3. Set strong master password (22+ chars)
4. Save master password → ~/.bitwarden_master_password (chmod 600)
5. Settings → Security → Keys → View API key
6. Confirm master password when prompted
7. Save client_id + client_secret → ~/.bitwarden_credentials (chmod 600):

   BW_CLIENTID="user.xxxxxxxx-..."
   BW_CLIENTSECRET="..."
   BW_PASSWORD="your-master-password"
   

chrome-devtools signup + API key

REMOTE="https://your-host/mcp"
# Navigate to signup
node chrome-devtools.js navigate_page --url "https://vault.bitwarden.com/#/signup" --remote "$REMOTE"
# ... fill form, verify email ...
# After login, navigate to Keys settings
node chrome-devtools.js navigate_page --url "https://vault.bitwarden.com/#/settings/security/session-timeout" --remote "$REMOTE"
# Click "Keys" tab (url: #/settings/security/security-keys)
node chrome-devtools.js click <keys-uid> --remote "$REMOTE"
# Click "View API key", fill master password, read client_id + client_secret from snapshot

Security → Keys page = #/settings/security/security-keys (not /keys).

Session setup (once per shell)

Unlock vault before any operation.

API key login (non-interactive — preferred):

# Requires: BW_CLIENTID, BW_CLIENTSECRET, BW_PASSWORD set in environment
source ~/.bitwarden_credentials   # or export vars manually
bw login --apikey
export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)
bw sync --session "$BW_SESSION"

Already logged in:

export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)
bw sync --session "$BW_SESSION"

Always bw sync after unlock to pull latest state.

List secrets

# All items (id, name, type)
bw list items --session "$BW_SESSION" | jq '[.[] | {id, name, type}]'

# Search by name
bw list items --search "github" --session "$BW_SESSION" | jq '[.[] | {id, name}]'

# List collections (org)
bw list collections --session "$BW_SESSION" | jq '[.[] | {id, name}]'

# Items in a specific collection
COLL_ID=$(bw list collections --session "$BW_SESSION" | jq -r '.[] | select(.name=="openclawbot") | .id')
bw list items --collectionid "$COLL_ID" --session "$BW_SESSION" | jq '[.[] | {id, name, type}]'

Types: 1=Login, 2=SecureNote, 3=Card, 4=Identity

Retrieve a secret

# Just the password
bw get password "github.com" --session "$BW_SESSION"

# Just the username
bw get username "github.com" --session "$BW_SESSION"

# Notes field (good for API keys, tokens stored as secure notes)
bw get notes "MY_API_KEY" --session "$BW_SESSION"

# Full item as JSON
bw get item "github.com" --session "$BW_SESSION" | jq .

bw get takes item name or UUID. Name match = case-insensitive substring.

Store a secret

Secure note (API keys, tokens, arbitrary strings):

bw get template item.secureNote \
  | jq --arg n "OPENAI_API_KEY" --arg v "sk-proj-..." '.name=$n | .notes=$v' \
  | bw encode | bw create item --session "$BW_SESSION" | jq '{id, name}'

Login item (username + password):

bw get template item.login \
  | jq --arg n "GitHub" --arg u "[e-mail]" --arg p "hunter2" \
    '.name=$n | .login.username=$u | .login.password=$p' \
  | bw encode | bw create item --session "$BW_SESSION" | jq '{id, name}'

Into a collection (org) — resolve collection + org IDs first:

ORG_ID=$(bw list organizations --session "$BW_SESSION" | jq -r '.[0].id')
COLL_ID=$(bw list collections --organizationid "$ORG_ID" --session "$BW_SESSION" \
  | jq -r '.[] | select(.name=="openclawbot") | .id')

# Create secure note in the collection
bw get template item.secureNote \
  | jq --arg n "CRYPTO_CALLBACK_SECRET" --arg v "my-secret-value" \
       --arg org "$ORG_ID" --argjson colls "[\"$COLL_ID\"]" \
    '.name=$n | .notes=$v | .organizationId=$org | .collectionIds=$colls' \
  | bw encode | bw create item --session "$BW_SESSION" | jq '{id, name}'

Note: Items in org collections require organizationId AND collectionIds array. Personal vault items use folders; shared/project secrets use org collections.

Create a collection (org)

ORG_ID=$(bw list organizations --session "$BW_SESSION" | jq -r '.[0].id')
# Create collection in the org
echo "{\"name\":\"openclawbot\",\"organizationId\":\"$ORG_ID\"}" \
  | bw encode | bw create org-collection --organizationid "$ORG_ID" --session "$BW_SESSION" | jq '{id, name}'

Update an item

ITEM=$(bw get item "github.com" --session "$BW_SESSION")
ITEM_ID=$(echo "$ITEM" | jq -r '.id')
echo "$ITEM" | jq '.login.password = "new-password"' \
  | bw encode | bw edit item "$ITEM_ID" --session "$BW_SESSION"

Lock / logout

bw lock          # invalidates BW_SESSION, vault stays logged in
bw logout        # full logout

Common mistakes

Mistake	Fix
Session key is invalid	Re-run export BW_SESSION=$(bw unlock ...)
Not logged in	Run bw login --apikey first
Stale data	bw sync --session "$BW_SESSION" before reads
bw get returns wrong item	Use UUID from bw list items instead of name
Passing session in plain text to scripts	Use --session "$BW_SESSION" not --session abc123 hardcoded
Installing via npm	Use GitHub binary — npm package was compromised April 2026