layered-soul/skills/vaultwarden-secrets/references/bw-cli-reference.md

bw CLI Reference

Quick-reference for the bw (Bitwarden) CLI against a self-hosted Vaultwarden instance.

Install

npm install -g @bitwarden/cli

On systems where node/npm aren't on default PATH (e.g. nvm-managed), use the full path:

~/.nvm/versions/node/v24.16.0/bin/npm install -g @bitwarden/cli
export PATH="$HOME/.nvm/versions/node/v24.16.0/bin:$PATH"

Login (headless API key)

bw config server https://vault.example.com
bw login --apikey
# Non-interactive: set BW_CLIENTID + BW_CLIENTSECRET env vars, then:
bw login --apikey

Unlock (headless)

BW_PASSWORD="master-password" bw unlock --passwordenv BW_PASSWORD
# Returns session key — capture BW_SESSION from output

Or combine: bw login --apikey && bw unlock --passwordenv BW_PASSWORD

Status

bw status  # {"status":"locked"} or {"status":"unlocked"}

Organization Collections

# List
bw list collections --organizationid <org-id> --session "$BW_SESSION"

# Sync (after creating new collections in web UI)
bw sync --session "$BW_SESSION"

Item CRUD

Create

echo '{"type":1,"name":"...","login":{"username":"...","password":"..."},"organizationId":"<org-id>"}' | \
  bw encode | bw create item --session "$BW_SESSION"

Get

bw get item "Item Name" --session "$BW_SESSION"
# Returns JSON including .login.password, .login.username, .login.uris

Get by ID (extract password)

bw get item <id> --session "$BW_SESSION" | python3 -c "import sys,json; print(json.load(sys.stdin)['login']['password'])"

Edit (e.g., move to collection)

bw get item <id> --session "$BW_SESSION" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); d['collectionIds']=['<col-id>']; print(json.dumps(d))" | \
  bw encode | bw edit item <id> --session "$BW_SESSION"

List all items

bw list items --session "$BW_SESSION" | python3 -c "import sys,json; [print(i['name']) for i in json.load(sys.stdin)]"

Lock

bw lock  # Locks vault, invalidates session

Item Types

type	Name
1	Login (username + password + URI)
2	Secure Note
3	Card
4	Identity

Pitfalls

• Organization API keys don't work with bw login --apikey. Use a personal API key (user.xxx).
• --organizationid flag is --organizationid not --organization-id.
• --collectionids flag doesn't exist on bw create item — use organizationId in the JSON body and set collectionIds via bw edit item after creation.
• Session tokens expire. Run bw status to check.
• After creating collections in the web UI, run bw sync before bw list collections.
• bw login --apikey is interactive — doesn't accept stdin piping. Use BW_CLIENTID + BW_CLIENTSECRET env vars for non-interactive use.
• On Vaultwarden you must first log out then log in: bw logout && bw login --apikey.

Forgejo integration example

bw get item "hermes-debby Forgejo" --session "$BW_SESSION" | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(f'user={d[\"login\"][\"username\"]} pass={d[\"login\"][\"password\"]}')"