Bitwarden CLI

intent

use the bitwarden command-line interface to authenticate with your vault, perform CRUD operations on login items/folders/collections, generate passwords, share secrets via Send, and manage organization memberships. use this skill when you need to retrieve passwords programmatically, create new vault entries in bulk, export/import from other password managers, or automate vault access in shell scripts and CI/CD pipelines.

inputs

• bitwarden cli: native executable from https://bitwarden.com/download/?app=cli or installed via npm (npm install -g @bitwarden/cli), chocolatey (choco install bitwarden-cli), or snap (snap install bw)
• master password: stored in BW_PASSWORD environment variable, sourced from ~/.openclaw/workspace/.secrets file (mode 600, git-ignored)
• email address (for email/password auth): stored in BW_EMAIL env var in .secrets
• api credentials (for api key auth): BW_CLIENTID and BW_CLIENTSECRET env vars from personal api key at https://bitwarden.com/help/personal-api-key/, stored in .secrets
• bitwarden account: active account on https://vault.bitwarden.com or self-hosted instance (e.g., vaultwarden)
• network access: outbound https to bitwarden cloud or self-hosted server
• jq: optional but recommended for json manipulation in create/edit pipelines
• self-signed cert path: if using self-hosted instance with untrusted certs, set NODE_EXTRA_CA_CERTS env var

procedure

step 1: prepare environment

input: none output: environment variables (BW_PASSWORD, BW_EMAIL, BW_CLIENTID, BW_CLIENTSECRET) loaded into current shell session

create .secrets file in workspace root with restricted permissions:

mkdir -p ~/.openclaw/workspace
cat >> ~/.openclaw/workspace/.secrets << 'EOF'
BW_PASSWORD=your_master_password
BW_EMAIL=your@email.com
BW_CLIENTID=user.xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
BW_CLIENTSECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOF
chmod 600 ~/.openclaw/workspace/.secrets
echo ".secrets" >> ~/.openclaw/workspace/.gitignore

source the file in the current shell:

set -a && source ~/.openclaw/workspace/.secrets && set +a

(optional) auto-source on new shell sessions by adding to ~/.bashrc or ~/.zshrc:

echo 'source ~/.openclaw/workspace/.secrets 2>/dev/null' >> ~/.bashrc

step 2: authenticate and unlock vault

input: BW_PASSWORD, BW_EMAIL (if email/password auth) or BW_CLIENTID/BW_CLIENTSECRET (if api key auth) output: BW_SESSION env var containing session token

attempt unlock first (fast path if already logged in):

export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw 2>/dev/null)

if unlock fails, perform login then unlock:

if [ -z "$BW_SESSION" ]; then
  # email/password login
  bw login "$BW_EMAIL" "$BW_PASSWORD"
  
  # OR api key login (if credentials exist)
  # bw login --apikey
  
  export BW_SESSION=$(bw unlock --passwordenv BW_PASSWORD --raw)
fi

verify authentication status:

bw status

expected output: locked (before unlock) or unlocked (after unlock).

step 3: sync vault with server

input: BW_SESSION (from step 2) output: local vault cache synced with cloud/self-hosted server

bw sync

run this before any vault read or write operation. check last sync timestamp with:

bw sync --last

step 4: perform vault operations (list, get, create, edit, delete)

input: operation type, item/folder/collection id or name, optional filters output: json response or raw value depending on command

4a. list items

list all items in vault:

bw list items

list with filters:

bw list items --search github              # by name
bw list items --url https://example.com    # by url
bw list items --folderid <id>              # by folder
bw list items --collectionid <id>          # by collection (org)
bw list items --trash                      # trash only

list folders, collections, organizations:

bw list folders
bw list collections
bw list organizations
bw list org-collections --organizationid <id>
bw list org-members --organizationid <id>

4b. get single values or full items

retrieve specific fields by name or id:

bw get password "GitHub"                   # password field
bw get username "GitHub"                   # username field
bw get totp "GitHub"                       # 2fa code
bw get notes "GitHub"                      # notes field
bw get uri "GitHub"                        # url field

retrieve full item as json:

bw get item "GitHub"
bw get item <uuid> --pretty

retrieve other object types:

bw get folder <id>
bw get collection <id>
bw get organization <id>
bw get org-collection <id> --organizationid <id>

download attachment:

bw get attachment <filename> --itemid <id> --output /path/

check password breach status:

bw get exposed <password>

4c. create new items

get templates for reference:

bw get template item
bw get template item.login
bw get template item.card
bw get template item.identity
bw get template item.securenote
bw get template folder
bw get template collection

create folder:

bw get template folder | jq '.name="Work"' | bw encode | bw create folder

create login item:

bw get template item | jq '.name="Service" | .login |= . + {username:"user@example.com", password:"secret"}' | bw encode | bw create item

create secure note (type=2):

bw get template item | jq '.type=2 | .secureNote.type=0 | .name="Note" | .notes="Content"' | bw encode | bw create item

create card (type=3):

bw get template item | jq '.type=3 | .name="My Card" | .card |= . + {number:"4111..."}' | bw encode | bw create item

create identity (type=4):

bw get template item | jq '.type=4 | .name="My Identity"' | bw encode | bw create item

create ssh key (type=5):

bw get template item | jq '.type=5 | .name="My SSH Key"' | bw encode | bw create item

attach file to existing item:

bw create attachment --file ./doc.pdf --itemid <uuid>

4d. edit existing items

retrieve item, modify json, re-encode and update:

bw get item <id> | jq '.login.password="newpass"' | bw encode | bw edit item <id>

edit folder:

bw get folder <id> | jq '.name="New Name"' | bw encode | bw edit folder <id>

edit item collections (org):

echo '["collection-uuid"]' | bw encode | bw edit item-collections <item-id> --organizationid <id>

4e. delete items (soft or permanent)

soft delete (recoverable for 30 days):

bw delete item <id>
bw delete folder <id>
bw delete attachment <id> --itemid <id>
bw delete org-collection <id> --organizationid <id>

permanent delete (irreversible):

bw delete item <id> --permanent

restore from trash:

bw restore item <id>

step 5: generate passwords or passphrases

input: password length, character sets, passphrase words/separator output: generated password or passphrase string

generate random password (default 14 chars):

bw generate
bw generate --uppercase --lowercase --number --special --length 20
bw generate -ulns --length 32

generate passphrase:

bw generate --passphrase --words 4 --separator "-" --capitalize --includeNumber

step 6: create secure shares (sends)

input: send name, data (text or file path), ttl (days), optional password output: shareable url

create text send (expires in 7 days):

bw send -n "Secret" -d 7 --hidden "This text vanishes in 7 days"

create file send (expires in 14 days):

bw send -n "Doc" -d 14 -f /path/to/file.pdf

create send with password protection:

bw send --password accesspass -f file.txt

step 7: access received sends

input: send url, optional password output: decrypted send content

bw receive <url> --password <pass>

step 8: manage organization

input: item id, organization id, user id, collection uuid output: json confirmation or member status

move item to organization collection:

echo '["collection-uuid"]' | bw encode | bw move <item-id> <organization-id>

get user fingerprint for security verification:

bw get fingerprint <user-id>
bw get fingerprint me

confirm organization member (after verifying fingerprint):

bw confirm org-member <user-id> --organizationid <id>

list and approve device requests:

bw device-approval list --organizationid <id>
bw device-approval approve <request-id> --organizationid <id>
bw device-approval approve-all --organizationid <id>
bw device-approval deny <request-id> --organizationid <id>
bw device-approval deny-all --organizationid <id>

step 9: import/export vault

input: source file path (import) or output path (export), format type output: imported items in vault or exported file at specified path

import from other password managers:

bw import --formats                          # list supported formats
bw import lastpasscsv ./export.csv
bw import bitwardencsv ./import.csv --organizationid <id>

export vault to csv:

bw export
bw export --output /path/export.csv --raw

export to json:

bw export --format json
bw export --format json --output /path/export.json --raw

export encrypted json (encrypted on disk with custom password):

bw export --format encrypted_json
bw export --format encrypted_json --password <custom-pass> --output /path/export.json

export with attachments as zip:

bw export --format zip --output /path/export.zip

export organization vault:

bw export --organizationid <id> --format json

step 10: lock and logout

input: none output: session cleared or logged out

lock vault (session persists, can unlock quickly):

bw lock

logout (complete session termination):

bw logout

decision points

• if already logged in with active session: run bw unlock --passwordenv BW_PASSWORD --raw (fast path). only proceed to bw login if unlock fails with empty output.

• if using api key authentication: check whether target bitwarden instance (self-hosted or cloud) supports bw login --apikey. on some vaultwarden instances, this fails with "User Decryption Options are required". if so, fall back to bw login "$BW_EMAIL" "$BW_PASSWORD" instead.

• if self-signed cert on self-hosted instance: before any bw command, set NODE_EXTRA_CA_CERTS=/path/to/cert.pem to bypass tls verification errors.

• if operation returns empty result set: (e.g., bw list items --search nonexistent returns []), this is not an error. proceed with empty handling in calling logic.

• if rate limit hit: bitwarden cloud enforces request throttling. back off exponentially (1s, 2s, 4s) before retry. this is rare in CLI usage but may occur with rapid api key logins.

• if session expires: bitwarden sessions last approximately 24 hours. if a command fails with "session invalid" or "unauthorized", re-run step 2 (unlock/login) to refresh BW_SESSION.

• if creating item from template and jq fails: validate json syntax with bw get template item | jq empty before piping to bw encode. use --pretty flag on bw get commands to debug json structure.

• if soft-delete recovery window expires: items deleted with bw delete item <id> remain in trash for 30 days only. after 30 days, permanent deletion is automatic. plan recovery workflows within this window.

• if vault not initialized (first time login): bw unlock will fail with "vault is empty" or similar. this is expected. proceed with bw login to initialize.

• if two-step login (2fa) required: add --method <code> and --code <value> flags to bw login:

  • --method 0 (authenticator app), --method 1 (email), --method 3 (yubikey)
  • example: bw login user@example.com password --method 0 --code 123456

• if exporting organization data: ensure user has admin or owner role. provide --organizationid <id> flag. non-admin users cannot export full org vault.

output contract

all operations return json by default (or raw text for specific queries like bw get password). success is indicated by:

• authentication: bw status returns unlocked state. BW_SESSION env var is set and non-empty.
• list operations: returns json array of objects with id, name, type fields and nested data. empty array [] is valid (no matches).
• get operations: single object or string value. example:

  {
    "object": "item",
    "id": "uuid",
    "name": "GitHub",
    "login": {
      "username": "user@example.com",
      "password": "secret",
      "totp": "otpauth://..."
    },
    "notes": "...",
    "fields": [...]
  }
  

• create operations: returns full created object json with assigned id and revisionDate.
• edit operations: returns updated object json.
• delete operations: returns empty response (no stdout) on success.
• password generation: returns string (e.g., aB3$x9Kl2m@pQ).
• send creation: returns send object with id and accessId for url construction.
• export: file written to specified path or stdout (if --raw). size depends on vault contents.
• import: returns count of imported items.

all responses use --pretty flag for human-readable formatting or --quiet to suppress stdout (for piping secrets).

error responses are json with statusCode and message fields (example: {"statusCode":401,"message":"Invalid credentials"}).

outcome signal

• authentication successful: bw status outputs locked or unlocked. no error thrown.
• vault operations complete: command returns json without error. example:

  bw get password "GitHub"
  # output: secretpassword (not redacted, handle with --quiet if needed)
  

• item created: new item appears in bw list items --search <name> and has assigned uuid.
• item edited: bw get item <id> reflects updated fields.
• item deleted: bw list items --trash shows soft-deleted item. bw list items no longer shows it.
• password generated: bw generate outputs a string with requested character set and length.
• send created: output includes url starting with https://vault.bitwarden.com/#/send/... (or custom domain). recipient can access via this url.
• vault synced: bw sync --last outputs recent timestamp. subsequent reads reflect server state.
• export completed: file exists at output path with expected size (non-zero).
• import completed: bw list items includes newly imported items.
• session locked: bw status returns locked after bw lock.
• logged out: bw status returns unauthenticated after bw logout.

configuration reference

config command

set bitwarden server endpoint (cloud or self-hosted):

bw config server https://vault.bitwarden.com           # default (cloud)
bw config server https://vault.bitwarden.eu            # EU cloud
bw config server https://vault.example.com             # self-hosted
bw config server                                        # check current

set individual service urls (advanced):

bw config server --web-vault <url> --api <url> --identity <url>

global flags (all commands)

--pretty                     # format json with indentation
--raw                        # output raw value (no json wrapper)
--response                   # json formatted response envelope
--quiet                      # suppress stdout (useful for piping secrets)
--nointeraction              # skip interactive prompts
--session <key>              # pass session directly (override BW_SESSION)
--version                    # show cli version
--help                       # show command help

rest api server

start local http api gateway (beta, not recommended for production):

bw serve --port 8087 --hostname localhost

troubleshooting

issue	solution
"Bot detected"	use --apikey login or set BW_CLIENTSECRET. cloud rate limits interactive logins.
"Vault is locked"	run bw unlock --passwordenv BW_PASSWORD and export BW_SESSION.
"Vault is empty"	first-time login. run bw login to initialize vault from server.
"User Decryption Options are required" (self-hosted)	use email/password login (bw login "$BW_EMAIL" "$BW_PASSWORD") instead of --apikey. some vaultwarden versions don't support api key auth.
"Self-signed cert rejected"	set NODE_EXTRA_CA_CERTS=/path/to/cert.pem before running bw commands.
"Session invalid" or "Unauthorized"	session expired (typically after 24h). re-authenticate with bw unlock or bw login.
"Command not found: jq"	install jq (brew install jq or apt-get install jq). needed for json manipulation in create/edit pipelines.
"Need debug output"	set export BITWARDENCLI_DEBUG=true before bw commands. very verbose.
"Can't find .secrets file"	ensure path is ~/.openclaw/workspace/.secrets and permissions are 600. verify with ls -la ~/.openclaw/workspace/.secrets.

best practices

1. unlock before login: try bw unlock first. only login if vault is not initialized. unlock is faster and avoids unnecessary api calls.
2. always sync: run bw sync before reading or writing vault data. local cache can lag server state.
3. secure session: export BW_SESSION only when needed. lock vault with bw lock when done. never log or print session tokens.
4. protect .secrets: keep file mode 600. add to .gitignore. never commit credentials to git.
5. auto-source credentials: add source ~/.openclaw/workspace/.secrets 2>/dev/null to ~/.bashrc or ~/.zshrc for automatic env var loading on new shells.
6. verify org member fingerprints: before confirming a new team member with bw confirm org-member, verify their fingerprint via out-of-band channel (voice, in-person, etc.) to prevent account spoofing.
7. handle errors in scripts: check exit code and stderr. example:

   if ! bw sync; then
     echo "sync failed" >&2
     exit 1
   fi
   

8. use --quiet for secrets: pipe passwords safely with bw get password <name> --quiet | xargs ... to avoid printing to terminal.
9. encrypt sensitive exports: use --format encrypted_json --password <strong-pass> when exporting vault for transport.
10. test on self-hosted first: if using vaultwarden or custom instance, test all commands locally before deploying to production automation.

references

• official cli docs: https://bitwarden.com/help/cli/
• markdown docs (for automation): https://bitwarden.com/help/cli.md
• personal api key setup: https://bitwarden.com/help/personal-api-key/
• vaultwarden project (self-hosted): https://github.com/dani-garcia/vaultwarden

---

Credits: original skill authored by tfm. enriched per implexa quality standards to include explicit decision points, edge case handling, environment setup guidance, and troubleshooting reference.