Bitwarden CLI (bw) Recipes for Vaultwarden
bw is the supported way to read and write vault content on Vaultwarden, because it performs the client-side encryption the server API expects. Connection and login: vaultwarden-dev:setup. Every recipe assumes BW_SESSION is exported (or --session "$BW_SESSION" is passed).
Ground rules
- Pipe JSON through
jqand select only the fields needed; keep passwords, TOTP seeds and notes inside$(...)captures. Command output becomes part of the conversation. - The plugin's guard hook asks before
bw list items/bw get itemrun uncaptured — including the filtered pipelines below, which it cannot prove safe. Approve those when thejqprojection drops the secret fields; only captured forms pass silently. - Run
bw syncbefore reads in long-lived sessions — the CLI works from a local encrypted cache. - Address items by id once found; names are not unique.
Find things
bw list items --search github | jq -r '.[] | [.id, .name, .login.username // ""] | @tsv'
bw list items --folderid <folder-id> | jq -r '.[] | [.id, .name] | @tsv'
bw list items --url https://git.example.com | jq -r '.[] | [.id, .name] | @tsv'
bw list items --organizationid <org-uuid> --collectionid <collection-id> | jq -r '.[] | [.id, .name] | @tsv'
bw list folders | jq -r '.[] | [.id, .name] | @tsv'
bw list organizations | jq -r '.[] | [.id, .name, .type] | @tsv'
bw list org-collections --organizationid <org-uuid> | jq -r '.[] | [.id, .name] | @tsv'
bw list org-members --organizationid <org-uuid> | jq -r '.[] | [.id, .email, .status, .type] | @tsv'
bw list items --trash lists deleted items. --search matches name, username and URIs.
Use a secret without printing it
export DB_PASSWORD="$(bw get password <item-id>)"
export API_TOKEN="$(bw get item <item-id> | jq -r '.fields[] | select(.name == "API_TOKEN") | .value')"
PGPASSWORD="$(bw get password <item-id>)" psql "postgresql://<db-user>@db.example.com:5432/<db>" -c 'select 1'
bw get username <item-id> # usernames are not secret, printing is fine
Run a program with several secrets in its environment, without writing them to disk or into any argv (a VAR=value cmd prefix sets the environment; env VAR=value cmd would put the value in env's arguments):
DB_PASSWORD="$(bw get password <db-item-id>)" \
STRIPE_KEY="$(bw get item <stripe-item-id> | jq -r '.fields[] | select(.name=="key") | .value')" \
./deploy.sh
Pattern for "secrets as env vars": store one secure note per service with custom fields named like the variables, then export every field:
while IFS=$'\t' read -r name value; do export "$name=$value"; done \
< <(bw get item <item-id> | jq -r '.fields[] | [.name, .value] | @tsv')
Create and edit
bw create and bw edit take base64-encoded JSON — always go through bw encode.
# Login item from the template
# (secrets reach jq through the environment, not through --arg, so they stay out of argv)
export NEW_PW="$(bw generate -ulns --length 32)"
bw get template item | jq --arg name "Staging DB" --arg user app \
'.type = 1 | .name = $name | .notes = null
| .login = {username: $user, password: env.NEW_PW, uris: [{uri: "postgresql://db.example.com", match: null}]}' \
| bw encode | bw create item | jq '{id, name}'
unset NEW_PW
# Secure note with custom fields (type 0 = text, 1 = hidden, 2 = boolean)
bw get template item | jq '.type = 2 | .secureNote = {type: 0} | .name = "ci-secrets"
| .fields = [{name: "API_TOKEN", value: "<value>", type: 1}]' | bw encode | bw create item | jq '{id, name}'
# Rotate a password in place
export NEW_PW="$(bw generate -ulns --length 32)"
bw get item <item-id> | jq '.login.password = env.NEW_PW' \
| bw encode | bw edit item <item-id> | jq '{id, revisionDate}'
unset NEW_PW
# Folder and org collection
bw get template folder | jq '.name = "Infra"' | bw encode | bw create folder | jq '{id, name}'
bw get template org-collection | jq --arg org <org-uuid> '.organizationId = $org | .name = "Infra"' \
| bw encode | bw create org-collection --organizationid <org-uuid> | jq '{id, name}'
Item types: 1 login, 2 secure note, 3 card, 4 identity, 5 SSH key.
Share, move, delete
# Move a personal item into an organization collection (re-encrypts with the org key)
echo '["<collection-id>"]' | bw encode | bw move <item-id> <org-uuid> | jq '{id, organizationId}'
bw delete item <item-id> # to trash, restorable
bw restore item <item-id>
bw delete item <item-id> --permanent # gone
Organization members — what only the CLI can do
bw list org-members --organizationid <org-uuid> | jq -r '.[] | select(.status == 1) | [.id, .email] | @tsv' # accepted, not confirmed
bw confirm org-member <member-id> --organizationid <org-uuid>
Confirmation encrypts the organization key to the member's public key. Compare the member's fingerprint phrase out of band first if the org requires it (bw get fingerprint <user-id>). Inviting, revoking and removing members works without crypto — see client API routes.
Generate
bw generate -ulns --length 32 # upper, lower, numbers, special
bw generate --passphrase --words 5 --separator - --capitalize --includeNumber
Backups and exports
# Encrypted, password-protected export — safe to store; restorable on any Bitwarden/Vaultwarden
bw export --format encrypted_json --password "$EXPORT_PASSWORD" --output "vault-$(date +%F).json"
bw export --organizationid <org-uuid> --format encrypted_json --password "$EXPORT_PASSWORD" --output "org-$(date +%F).json"
bw export accepts the export password only as --password (no env or stdin option), so it is visible in the process list while the export runs — run it on a machine you control. Plain --format json / csv writes every password in clear text; the guard hook asks before it runs. A vault export is not a server backup — server-side backup is in vaultwarden-dev:admin-panel.
Local REST API: bw serve
For long-running integrations, bw serve keeps one unlocked session and exposes a local HTTP API (Vault Management API) — no Node process per call. Endpoints, start-up and safety rules: references/bw-serve.md.
Flags and environment
| Flag / variable | Effect |
|---|---|
--session <key> / BW_SESSION |
unlocked session to use |
--raw |
print only the value (no JSON envelope / no message) |
--pretty |
indent JSON |
--nointeraction |
never prompt; fail instead — use in scripts |
--response |
wrap output in {success, data} JSON |
BW_CLIENTID, BW_CLIENTSECRET |
personal API key for bw login --apikey |
BITWARDENCLI_APPDATA_DIR |
separate CLI state per account or server |
NODE_EXTRA_CA_CERTS |
trust a private CA in front of Vaultwarden |
BITWARDENCLI_DEBUG=true |
verbose HTTP logging (contains tokens — do not share) |