Bitwarden CLI: the password manager in your terminal

Install the CLI

The CLI is the bw command, published as @bitwarden/cli on npm and as standalone binaries for Windows, macOS and Linux under the cli-v* tags of the bitwarden/clients releases. The releases page on this site tracks the current version.

npm install -g @bitwarden/cli

brew install bitwarden-cli

sudo snap install bw

choco install bitwarden-cli

Check it with bw --version. The CLI is independent of the desktop app; if you want that too, the one-command install is on the home page.

Log in, unlock and the session key

The CLI has two states. Logged in means it holds your encrypted vault on disk. Unlocked means it also has the key to decrypt it, as a session key that you pass to every command.

1. Log in with your email address, master password and two-step code. Add --apikey to authenticate instead with a personal API key from the web vault’s Security settings, read from BW_CLIENTID and BW_CLIENTSECRET.

bw login

2. Unlock. The CLI prints a session key and the exact export line to paste.

bw unlock

3. Export the key so later commands find it, either by pasting that line or in one step:

export BW_SESSION="$(bw unlock --raw)"

4. Sync, then read a password.

bw sync

bw get password github.com

5. Lock when finished. bw lock invalidates the session key but keeps you logged in; bw logout also removes the local vault copy.

bw lock

Without the export, every command needs --session <key>. EU accounts run bw config server https://vault.bitwarden.eu before the first login.

The commands you will use most

bw list items --search github

bw generate -ulns --length 24

bw get accepts an item name or its UUID; if a name matches several items the command fails and lists them, so copy the ID from that output. -ulns means uppercase, lowercase, numbers and symbols. list and get item output JSON, which is why jq appears in every Bitwarden script.

Create, edit and delete items

Items are created from a JSON template that you fill in, base64-encode and pass to bw create:

bw get template item | jq \
  --arg name "Example" \
  --arg user "me@example.com" \
  --arg pass "$(bw generate -ulns --length 24)" \
  '.name = $name
   | .login = {username: $user, password: $pass, uris: [{uri: "https://example.com"}]}' \
| bw encode | bw create item

Editing starts from the existing item instead of the template:

ID="$(bw get item example | jq -r .id)"
bw get item "$ID" | jq '.login.password = "new-password"' | bw encode | bw edit item "$ID"

Deleting moves an item to the trash; add --permanent to skip it.

bw delete item <id>

Import, export and server URL

The CLI imports the same formats as the web vault. List them, then import:

bw import --formats

bw import lastpasscsv export.csv

Delete the export file afterwards. The web vault route is described in import from LastPass and the other migration guides.

Exports go to the current directory unless you pass --output. Prefer the encrypted format; plain json and csv are readable by anything.

bw export --format encrypted_json

To use the EU cloud or your own server, log out, set the URL, then log in again:

bw config server https://vault.bitwarden.eu

For a self-hosted Bitwarden or Vaultwarden instance use its HTTPS address, for example bw config server https://vault.example.com; setting one up is covered in self-host Bitwarden or Vaultwarden.

bw serve: a local REST API

bw serve starts an HTTP server on localhost:8087 exposing the unlocked vault as REST endpoints (GET /object/item/<id>, POST /unlock and so on). It suits tools that cannot shell out repeatedly and avoids the Node start-up cost of each call.

bw serve --port 8087

Treat it with care: any process on the machine that can reach that port can read every item while the vault is unlocked, with no further authentication. Never bind it to a non-loopback address, never run it on a shared machine, and stop it when the job is done.

Scripting safely

• Never put the master password in a script, a crontab or a command line argument; arguments show up in ps output and shell history.
• Authenticate non-interactively with an API key: export BW_CLIENTID and BW_CLIENTSECRET, then bw login --apikey. The API key can log in but cannot decrypt anything by itself.
• Unlock with --passwordenv VAR (the master password in a variable your secret store injects) or --passwordfile /path on a file with mode 600 owned by the job’s user.
• Use --raw so output is only the value you asked for, --nointeraction so a missing input fails instead of prompting, and --response for structured JSON including error details.
• Keep BW_SESSION out of history: read it from bw unlock --raw in a subshell as shown above, or set HISTCONTROL=ignorespace and start the line with a space.
• Lock at the end of the script. CLI state lives under ~/.config/Bitwarden CLI/ on Linux, ~/Library/Application Support/Bitwarden CLI/ on macOS and %APPDATA%\Bitwarden CLI\ on Windows; restrict access to it.

For secrets that servers read, Bitwarden’s separate Secrets Manager and its bws CLI are built for machine access tokens with scoped projects; the password manager CLI is best for secrets that people also use.

Shell integration ideas

A picker that searches your logins with fzf and copies the password to the clipboard:

# Requires jq and fzf. Replace pbcopy with wl-copy or xclip -selection clipboard on Linux.
bw list items \
  | jq -r '.[] | select(.type == 1) | "\(.name)\t\(.login.username // "")\t\(.id)"' \
  | fzf --with-nth=1,2 --delimiter='\t' \
  | cut -f3 \
  | xargs bw get password \
  | pbcopy

Other useful patterns: a shell function that runs bw unlock --raw and exports the key once per terminal, bw get totp piped to the clipboard for two-step prompts, and bw list items --folderid to load a project’s credentials into environment variables.

On Linux, rbw is an unofficial Rust client with a background agent that holds the decrypted key and re-locks on a timer, so there is no session variable to manage and each call starts in milliseconds. It is not from Bitwarden and lacks some features, but it is popular for exactly this use.

Troubleshooting

• npm install -g fails with EACCES. The global prefix is owned by root. Use a Node version manager (nvm, fnm, volta) so the global directory is in your home, or set npm config set prefix ~/.local and add ~/.local/bin to PATH. Do not sudo npm install.
• “You are not logged in.” You never ran bw login on this machine, or the data directory was cleared. Log in again.
• “Vault is locked.” BW_SESSION is not set in this shell. Unlock and export the key, or pass --session.
• “mac failed” or “Invalid session key.” The key you are passing belongs to an older unlock. Unlock again and export the new key.
• bw is slow to start. Each call starts a Node runtime, roughly a second. Batch work with bw list items and jq, or use bw serve or rbw.
• Node version error. The current release needs Node 20 or later and distribution packages are often older. Use a version manager or the standalone binary. Ubuntu users who also want the desktop app will find the package options in install on Ubuntu.