Bitwarden

Manage secrets via Bitwarden CLI (bw). Use when pulling secrets into a shell session, creating/updating Secure Notes from .env files, listing vault items, or...

Security Scan

This is a Bitwarden CLI helper that mostly does what it claims, but the runtime instructions and included functions perform unsafe operations (blind eval of vault notes, a helper that will upload all shell environment variables, and use of env vars not declared in metadata), so you should review and understand the risks before installing.

Purpose & Capability

The name/description match the delivered artifacts: a Bitwarden CLI helper that requires bw and jq and provides shell functions. However, the SKILL.md and functions expect API-login environment variables (BW_CLIENTID, BW_CLIENTSECRET, BW_SESSION, BW_MASTER_PASSWORD) even though requires.env lists none — that mismatch should be justified.

Instruction Scope

The provided functions instruct the agent/user to source the script into shell startup files and then perform eval of remote data: `bwe()` performs `eval $(bw get item <name> | jq -r '.notes')` and `bwss()` uses eval on bw unlock output. `bwe_safe` reduces risk but still evals exported values (so command-substitution in values would execute). The `bwce` function collects all exported environment variables and uploads them into a Secure Note (possible silent exfiltration of unrelated secrets). These behaviors go beyond simple listing/loading and require careful trust of vault contents and the skill source.

Install Mechanism

Install options are standard: Homebrew formula (bitwarden-cli), snap, or npm. These are reasonable and expected for installing the bw binary. The SKILL.md also suggests installing the skill from an external repo (git clone or npx clawhub), so users should verify the repository source before cloning/sourcing code.

Credentials

The skill metadata declares no required env vars, but the instructions explicitly ask you to export BW_CLIENTID and BW_CLIENTSECRET (API key login) and handle BW_MASTER_PASSWORD/BW_SESSION. Additionally, `bwce` will capture and upload all exported environment variables (including unrelated/secrets like cloud credentials) into Bitwarden — this is powerful and potentially dangerous. The number and sensitivity of environment interactions are disproportionate to a passive 'list/get' helper unless you intentionally use the creation helpers.

Persistence & Privilege

The SKILL.md recommends adding a source line to ~/.bashrc to persist the functions, which modifies user shell startup files (expected for shell helpers). always:false and no cross-skill config modifications are set, so there is no elevated platform privilege, but persisting the script into shell startup increases the impact of any unsafe function in the file.

What to consider before installing

This skill implements useful Bitwarden shell helpers but includes risky behaviors you must accept knowingly: it blindly evals text fetched from your vault (so a malicious or compromised vault item could execute commands), and it includes a function (bwce) that captures and uploads all exported environment variables — which can leak unrelated secrets. Before installing: (1) review the included lib/bw-functions.sh source yourself (or only source a vetted copy), (2) prefer using bwe_safe and manually inspect notes before eval, (3) do not run bwce on machines with unrelated credentials, (4) use a machine account limited to a single collection for automated loads, (5) ensure the skill's repo/source is trustworthy before adding a 'source' line to your shell profile, and (6) ask the publisher to update the metadata to declare the BW_* env vars the instructions require. If you want a lower-risk setup, avoid automatic eval and instead fetch notes and manually export/parse trusted values.

Bitwarden CLI — Secrets Management

Core Concept

Secrets are stored as Bitwarden Secure Notes with export KEY='value' lines in the notes field. One eval call loads them into the current shell. No files on disk. Secrets die with the session.

Shell Functions

All functions ship in lib/bw-functions.sh — source it in your shell profile. No copy-pasting, no dotfiles dependency.

Setup on a new machine

# 1. Install bw CLI
brew install bitwarden-cli    # macOS
sudo snap install bw          # Ubuntu
npm i -g @bitwarden/cli       # any OS

# 2. Install skill (choose one)
npx clawhub install bitwarden-bwe            # via ClawHub
# or: git clone https://github.com/stevengonsalvez/clawdbot /path/to/clawdbot

# 3. Source functions in your shell profile
echo 'source /path/to/skills/bitwarden-bwe/lib/bw-functions.sh' >> ~/.bashrc
source ~/.bashrc

# 4. Login + unlock
export BW_CLIENTID="user.xxxxx"
export BW_CLIENTSECRET="xxxxx"
bw login --apikey
bwss   # unlock (prompts for master password)

# 5. Verify
bwl    # list vault items

What's in lib/bw-functions.sh

Function	Purpose
bwss	Unlock vault, set BW_SESSION interactively
bwe <name>	Load secrets from Secure Note into env via eval
bwe_safe <name>	Same, but only evals lines matching export VAR=value — defence-in-depth for shared orgs
bwc <name> [file]	Create Secure Note from .env file (auto-quotes values, uses mktemp + chmod 600)
bwce <name>	Create Secure Note from current shell exports
bwdd <name>	Delete item by name
bwl	Alias: list all item names
bwll <grep>	Alias: search item names
bwg <name>	Alias: get full item JSON

Notes on bwe_safe: Guards against non-export lines being injected but does not sanitize values — a value containing $(cmd) or backticks would still execute during eval. If someone has write access to your Bitwarden vault, you have bigger problems. Use on shared org accounts as a defence-in-depth layer.

References

• lib/bw-functions.sh — sourceable shell functions (the canonical implementation)
• references/cli-reference.md — Bitwarden CLI install, auth, and common operations

Workflow

Daily use

bwss                     # Unlock vault (once per terminal session)
bw sync                  # Pull latest from server (if secrets were updated in web vault)
bwe agent-fleet          # Load all agent secrets
echo $ANTHROPIC_API_KEY  # Verify — should be set

Creating / updating secrets

# From a .env file
bwc my-new-project .env

# From current shell
bwce snapshot-2026-03-03

# Update an existing note (delete + recreate)
bwdd old-note
bwc old-note .env.updated

# Or edit in web vault — notes field, one `export KEY='value'` per line

Org + Collection pattern (team/fleet use)

For sharing secrets with a machine account (e.g., GCP VM):

1. Create a Bitwarden Organization (free tier = 2 users)
2. Create a Collection in the org (e.g., popa-secrets)
3. Create a machine account — separate Bitwarden account, invited to org, assigned to the collection
4. Add Secure Notes to the collection with export KEY='value' format
5. On the target machine: install skill, source lib/bw-functions.sh, login with machine account API key, bwss, bwe <note>

The machine account sees ONLY items in its assigned collection. Revoke access = remove from org. One click.

Creating items in a collection (programmatic)

COLLECTION_ID="<collection-uuid>"
ORG_ID="<org-uuid>"
NOTES=$(cat .env | awk '{print "export " $0}')

bw get template item | jq \
  --arg notes "$NOTES" \
  --arg name "my-item" \
  --arg orgId "$ORG_ID" \
  --argjson colIds "[\"$COLLECTION_ID\"]" \
  '.type = 2 | .secureNote.type = 0 | .notes = $notes | .name = $name | .organizationId = $orgId | .collectionIds = $colIds' \
  | bw encode | bw create item

Listing collections and orgs

bw list organizations | jq '.[] | {id, name}'
bw list collections | jq '.[] | {id, name}'
bw list items --collectionid <id> | jq '.[] | .name'

Secure Note Format

Each Secure Note's notes field contains one secret per line:

export ANTHROPIC_API_KEY='sk-ant-...'
export OPENAI_API_KEY='sk-proj-...'
export DISCORD_TOKEN='MTQ3...'

Rules:

• One export KEY='value' per line
• Always single-quote values. Unquoted values containing |, !, #, $, backticks, or other shell metacharacters will break or execute during eval. Single quotes prevent this.
• No comments, no blank lines (they get eval'd)
• Keys should be UPPER_SNAKE_CASE
• If a value itself contains a single quote, use '\'' to escape it: export KEY='value'\''s edge case'
• Never put shell commands in values

Guardrails

• Never paste secrets into chat, logs, or code. Use bwe to load into memory only.
• Never write secrets to disk unless absolutely necessary (and chmod 600 if you must).
• Prefer bwe over ~/.secrets/ files. Secrets in memory > secrets on disk.
• Use bwe_safe on shared/org accounts. Defence in depth against note tampering.
• bwss once per terminal session. The session token persists until the shell exits.
• Sync before pulling: bw sync if you've recently updated secrets in the web vault.
• Lock when done: bw lock to clear the session token.

Tmux Considerations

If using bw inside tmux (common for agents), the BW_SESSION env var must be available in the tmux pane. Either:

• Run bwss inside the tmux pane, or
• Export BW_SESSION before creating the tmux session

# Option 1: unlock inside tmux (preferred — interactive, no password in process list)
tmux new-session -d -s work
tmux send-keys -t work 'bwss' Enter
# ... wait for unlock prompt, enter master password ...
tmux send-keys -t work 'bwe agent-fleet' Enter

# Option 2: pass session token via env var (non-interactive)
# ⚠️ Never pass the master password as a CLI argument — it's visible in `ps aux`.
# Use --passwordenv instead:
read -s BW_MASTER_PASSWORD && export BW_MASTER_PASSWORD
export BW_SESSION=$(bw unlock --passwordenv BW_MASTER_PASSWORD --raw)
unset BW_MASTER_PASSWORD
tmux new-session -d -s work -e "BW_SESSION=$BW_SESSION"
tmux send-keys -t work 'bwe agent-fleet' Enter

Quick Reference

Command	What it does
bwss	Unlock vault, set BW_SESSION
bwe <name>	Load secrets from note into env
bwe_safe <name>	Same, with input validation
bwc <name> [file]	Create note from .env file
bwce <name>	Create note from current exports
bwdd <name>	Delete item by name
bwl	List all item names
bwll <grep>	Search item names
bwg <name>	Get full item JSON
bw sync	Pull latest from server
bw lock	Clear session token