Bitwarden CLI

The Bitwarden command-line interface (CLI) is a powerful, fully-featured tool for accessing and managing your Vault. Most features that you find in other Bitwarden client applications (Desktop, Browser Extension, etc.) are available from the CLI.

The Bitwarden CLI is self-documented. From the command line, learn about the available commands using:

bw --help

Or, pass --help as an option on any bw command to see available options and examples:

bw list --help

bw move --help

Most information you’ll need can be accessed using --help, however this article replicates all that information and goes into greater depth on some topics.

Download and Install

The CLI can be used cross-platform on Windows, macOS, and Linux distributions. To download and install the Bitwarden CLI:

• Native Executable
• NPM
• Chocolatey
• Homebrew
• Snap

bash chmod +x </path/to/executable>

npm install -g @bitwarden/cli

choco install bitwarden-cli

brew install bitwarden-cli

sudo snap install bw

Log In

There are three methods for logging in to the Bitwarden CLI using the login command, each of which is suited to different situations. Please review the following options to determine which method to use:

• Using Email and Password
• Using an API Key
• Using SSO

Using Email and Password

Logging in with email and password is recommended for interactive sessions. To log in with email and password:

bw login

This will initiate a prompt for your Email address, Master password, and (if enabled) a Two-step login code. The CLI currently supports Two-step login via authenticator, email, or Yubikey.

You can string these factors together into a single command as in the following example, however this is not recommended for security reasons.

bw login [email] [password] --method <method> --code <code>

See Appendices → Enums for Two-step Login <method> values.

Using an API Key

Logging in with the Personal API Key is recommended for automated workflows or providing access to an external application. To log in with the API Key:

bw login --apikey

This will initiate a prompt for your personal client_id and client_secret. Once your session is authenticated using these values, you can use the unlock command (learn more).

Using API Key Environment Variables

In scenarios where automated work is being done with the Bitwarden CLI, you can save environment variables to prevent the need for manual intervention at authentication.

Using SSO

Logging in with the SSO is recommended if an Organization requires SSO Authentication. To log in with SSO:

bw login --sso

This will initiate the SSO authentication flow in your web browser. Once your session is authenticated, you can use the unlock command (learn more).

Unlock

Using an API Key or SSO to log in will require you to follow-up the login command with an explicit bw unlock if you will be working with Vault data directly.

Unlocking your Vault generates a session key which acts as a session-specific decryption key used to interact with data in your Vault. The session key must be used to perform any command that touches Vault data (e.g. list, get, edit). Generate a new session key at any time using:

bw unlock

Unlock Options

You can use the --passwordenv <passwordenv> or --passwordfile <passwordfile> options with bw unlock to retrieve your Master Password rather than enter it manually as in the following examples:

1. bw unlock --passwordenv BW_PASSWORD
   

   will look for an environment variable BW_PASSWORD. If BW_PASSWORD is non-empty and has correct values, the CLI will successfully and unlock and return a session key.

2. bw unlock --passwordfile ~/Users/Me/Documents/mp.txt
   

   will look for the file ~Users/Me/Documents/mp.txt (which must have your Master Password as the first line). If the file is non-empty and has a correct value, the CLI will successfully unlock and return a session key.

   Warning

   If you use the --passwordfile option, protect your password file by locking access down to only the user who needs run bw unlock and only providing read access to that user.

Using a Session Key

When you unlock your Vault using bw login with email and password or bw unlock, the CLI will return both a export BW_SESSION (Bash) and env:BW_SESSION (PowerShell) command, including your session key. Copy and paste the relevant entry to save the required environment variable.

With the BW_SESSION environment variable set, bw commands will reference that variable and can be run cleanly, for example:

export BW_SESSION="5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w=="

bw list items

Alternatively, if you don’t set the environment variable, you can pass the session key as an option with each bw command:

bw list items --session "5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w=="

bw lock

Core Commands

create

The create command creates a new object (item, attachment, etc.) in your Vault:

bw create (item|attachment|folder|org-collection) <encodedJson> [options]

The create command takes encoded JSON. A typical workflow for creating an object might look something like:

1. Use the get template command (see details) to output the appropriate JSON template for the object type.
2. Use a command-line JSON processor like jq to manipulate the outputted template as required.
3. Use the encode command (see details) to encode the manipulated JSON.
4. Use the create command to create an object from the encoded JSON.

For example:

bw get template folder | jq '.name="My First Folder"' | bw encode | bw create folder

or

bw get template item | jq ".name=\"My Login Item\" | .login=$(bw get template item.login | jq '.username="jdoe" | .password="myp@ssword123"')" | bw encode | bw create item

Upon successful creation, the newly created object will be returned as JSON.

create attachment

The create attachment command attaches a file to an existing item.

Unlike other create operations, you don’t need to use a JSON processor or encode to create an attachment. Instead, use the --file option to specify the file to attach and the --itemid option to specify the item to attach it to. For example:

bw create attachment --file ./path/to/file --itemid 16b15b89-65b3-4639-ad2a-95052a6d8f66

get

The get command retrieves a single object (item, username, password, etc.) from your Vault:

bw get (item|username|password|uri|totp|exposed|attachment|folder|collection|organization|org-collection|template|fingerprint) <id> [options]

The get command takes an item id or string for its argument. If you use a string (i.e. anything other than an exact id), get will search your Vault objects for one with a value that matches. For example, the following command would return a Github password:

bw get password Github

get attachment

The get attachment command downloads a file attachment:

bw get attachment <filename> --itemid <id>

The get attachment command takes a filename and exact id. By default, get attachment will download the attachment to the current working directory. You can use the --output option to specify a different output directory, for example:

bw get attachment photo.png --itemid 99ee88d2-6046-4ea7-92c2-acac464b1412 --output /Users/myaccount/Pictures/

get notes

The get notes command retrieves the note for any Vault item:

bw get notes <id>

get notes takes an exact item id or string. If you use a string (i.e. anything other than an exact id), getnotes will search your Vault objects for one with a value that matches. For example, the following command would return a Github note:

bw get notes Github

get template

The get template command returns the expected JSON formatting for an object (item, item.field, item.login, etc.):

bw get template (item|item.field|item.login|item.login.uri|item.card|item.identity|item.securenote|folder|collection|item-collections|org-collection)

While you can use get template to output the format to your screen, the most common use-case is to pipe the output into a bw create operation, using a command-line JSON processor like jq and bw encode to manipulate the values retrieved from the template, for example:

bw get template folder | jq '.name="My First Folder"' | bw encode | bw create folder

bw get template item | jq ".name=\"My Login Item\" | .login=$(bw get template item.login | jq '.username="jdoe" | .password="myp@ssword123"')" | bw encode | bw create item

edit

The edit command edits an object (item, item-collections, etc.) in your Vault:

bw edit (item|item-collections|folder|org-collection) <id> [encodedJson] [options]

The edit command takes an exact id (the object to edit) and encoded JSON (edits to be made). A typical workflow might look something like:

1. Use the get command (see details) to output the object to edit.
2. Use a command-line JSON processor like jq to manipulate the outputted object as required.
3. Use the encode command (see details) to encode the manipulated JSON.
4. Use the edit command (including the object id) to edit the object.

For example:

bw get item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328 | jq '.login.password="newp@ssw0rd"' | bw encode | bw edit item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328

Or, to edit a Collection:

bw get collection ee9f9dc2-ec29-4b7f-9afb-aac8010631a1 | jq '.name="My Collection"' | bw encode | bw edit item-collections ee9f9dc2-ec29-4b7f-9afb-aac8010631a1

The edit command will perform a replace operation on the object. Upon success, the updated object will be returned as JSON.

list

The list command retrieves an array of objects (items, folders, collections, etc.) from your Vault:

bw list (items|folders|collections|organizations|org-collections|org-members) [options]

Options for the list command are filters used to dictate what will be returned, including --url <url>, --folderid <folderid>, --collectionid <collectionid>, --organizationid <organizationid> and --trash. Any filter will accept null or notnull. Combining multiple filters in one command will perform a logical OR operation, for example:

bw list items --folderid null --collectionid null

This command will return items that are not in a folder or Collection.

Additionally, you can search for specific objects using --search <search-term>. Combining filter and search in one command will perform a logical AND operation, for example:

bw list items --search github --folderid 9742101e-68b8-4a07-b5b1-9578b5f88e6f

This command will search for items with the string github in the specified folder.

delete

The delete command deletes an object from your Vault. delete takes only an exact id for its argument.

bw delete (item|attachment|folder|org-collection) <id> [options]

By default, delete will “soft delete” an item (i.e. send it to the Trash). You can permanently delete an item using the -p, --permanent option.

bw delete item 7063feab-4b10-472e-b64c-785e2b870b92 --permanent

To delete an org-collection, you’ll also need to specify --organizationid <organizationid>. See Organization IDs.

restore

The restore command restores a deleted object from your Trash. restore takes only an exact id for its argument.

bw restore (item) <id> [options]

For example:

bw restore item 7063feab-4b10-472e-b64c-785e2b870b92

send

The send command creates a Bitwarden Send object for ephemeral sharing. This section will detail simple send operations, however Send is a highly flexible tool and we recommend referring to the dedicated article on Send from CLI.

To create a simple text Send:

bw send -n "My First Send" -d 7 --hidden "The contents of my first text Send."

To create a simple file Send:

bw send -n "A Sensitive File" -d 14 -f /Users/my_account/Documents/sensitive_file.pdf

receive

The receive command accesses a Bitwarden Send object. To receive a Send object:

bw receive --password passwordforaccess https://vault.bitwarden.com/#/send/yawoill8rk6VM6zCATXv2A/9WN8wD-hzsDJjfnXLeNc2Q

Organizations Commands

Organization IDs

Accessing an Organization from the CLI frequently requires knowledge of an ID for your Organization, as well as IDs for individual members and Collections.

Retrieve this information directly from the CLI using bw list, for example:

bw list organizations
bw list org-members --organizationid 4016326f-98b6-42ff-b9fc-ac63014988f5
bw list org-collections --organizationid 4016326f-98b6-42ff-b9fc-ac63014988f5

move

The move command transfers a Vault item to an Organization:

bw move <itemid> <organizationid> [encodedJson]

The move command requires you to encode a Collection ID, and takes an exact id (the object to share) and an exact organizationid (the Organization to share the object to). For example:

echo '["bq209461-4129-4b8d-b760-acd401474va2"]' | bw encode | bw move ed42f44c-f81f-48de-a123-ad01013132ca dfghbc921-04eb-43a7-84b1-ac74013bqb2e

Upon success, the updated item will be returned.

confirm

The confirm command confirms invited members to your Organization who have accepted their invitation:

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

The confirm command takes an exact member id and an exact organizationID, for example:

bw confirm org-member 7063feab-4b10-472e-b64c-785e2b870b92 --organizationid 310d5ffd-e9a2-4451-af87-ea054dce0f78

Other Commands

config

The config command specifies settings for the Bitwarden CLI to use:

bw config <setting> [value]

A primary use of bw config is to connect your CLI to a self-hosted Bitwarden server:

bw config server https://your.bw.domain.com

Users with unique setups may elect to specify the URL of each service independently using:

bw config --web-vault <url>
bw config --api <url>
bw config --identity <url>
bw config --icons <url>
bw config --notifications <url>
bw config --events <url>

sync

The sync command downloads your encrypted vault from the Bitwarden server. This command is most useful when you’ve changed something in your Bitwarden Vault on another client application (e.g. Web Vault, Browser Extension, Mobile App) since logging in on the CLI.

bw sync

You can pass the --last option to return only the timestamp (ISO 8601) of the last time a sync was performed.

encode

The encode command Base 64 encodes stdin. This command is typically used in combination with a command-line JSON processor like jq when performing create and edit operations, for example:

bw get template folder | jq '.name="My First Folder"' | bw encode | bw create folder

bw get item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328 | jq '.login.password="newp@ssw0rd"' | bw encode | bw edit item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328

import

The import command imports data from a prior Bitwarden export or other supported password management application:

bw import <format> <path>

For example:

bw import lastpasscsv /Users/myaccount/Documents/mydata.csv

export

The export command exports Vault data as a .json or .csv, or encrypted .json file:

bw export [password] [--output <filePath>] [--format <format>] [--organizationid <orgid>]

The export command always requires your Master Password, even with an active session key.

By default, the export command will generate a .csv (equivalent to specifying --format csv) to the current working directory, however you can specify:

• --format json to export a .json file.
• --format encrypted_json to export an encrypted .json file.
• --output <path> to export to a specific location.
• --raw to return the export to stdout instead of to a file.

export an Organization Vault

Using the export command with the --organizationid option, you can export an Organization Vault:

bw export myp@ssw0rd --organizationid 7063feab-4b10-472e-b64c-785e2b870b92 --format json --output /Users/myaccount/Downloads/

generate

The generate command generates a strong password or passphrase:

bw generate [--lowercase --uppercase --number --special --length <length> --passphrase --separator <separator> --words <words>]

By default, the generate command will generate a 14-character password with uppercase characters, lowercase characters, and numbers. This is the equivalent of passing:

bw generate -uln --length 14

You can generate more complex passwords using the options available to the command, including:

• --uppercase, -u (include uppercase)
• --lowercase, -l (include lowercase)
• --number, -n (include numbers)
• --special, -s (include special characters)
• --length <length> (length of the password, min. of 5)

generate a passphrase

Using the generate command with the --passphrase option, you can generate a passphrase instead of a password:

bw generate --passphrase --words <words> --separator <separator>

By default, bw generate --passphrase will generate a 3-word passphrase separated by a dash (-). This is the equivalent of passing:

bw generate --passphrase --words 3 --separator -

You can generate a complex passphrase using the options available to the command, including:

• --words <words> (number of words)
• --separator <separator> (separator character)
• --capitalize, -c (include to title-case the passphrase)
• --includeNumber (include numbers in the passphrase)

update

The update command checks whether your Bitwarden CLI is running the most recent version. update does not automatically update the CLI for you.

bw update

If a new version is detected, you’ll need to download the new version of the CLI using the printed URL for the executable, or using the tools available for the package manager you used to download the CLI (e.g. npm install -g @bitwarden/cli).

status

The status command returns status information about the Bitwarden CLI, including configured server URL, timestamp for the last sync (ISO 8601), user email and ID, and the Vault status.

bw status

Status will return information as a JSON object, for example:

{
  "serverUrl": "https://bitwarden.example.com",
  "lastSync": "2020-06-16T06:33:51.419Z",
  "userEmail": "user@example.com",
  "userId": "00000000-0000-0000-0000-000000000000",
  "status": "unlocked"
}

status may be one of the following:

• "unlocked", indicating you are logged in and your Vault is unlocked (i.e. a BW_SESSION key environment variable is saved with an active session key).
• "locked", indicating you are logged in but your Vault is locked (i.e. no BW_SESSION key environment variable is saved with an active session key)
• "unauthenticated", indicating you aren’t logged in.

Appendices

Global Options

The following options are available globally:

ZSH Shell Completion

The Bitwarden CLI includes support for ZSH shell completion. To setup shell completion, use one of the following methods:

1. Vanilla ZSH: Add the following line to your .zshrc file:

   eval "$(bw completion --shell zsh); compdef _bw bw;"
   

2. Vanilla (vendor-completions): Run the following command:

   bw completion --shell zsh | sudo tee /usr/share/zsh/vendor-completions/_bw
   

3. zinit: Run the following commands:

   bw completion --shell zsh > ~/.local/share/zsh/completions/_bw
   zinit creinstall ~/.local/share/zsh/completions
   

Using Self-signed Certificates

If your self-hosted Bitwarden server exposes as self-signed TLS certificate, specify the Node.js environment variable NODE_EXTRA_CA_CERTS:

Bash

export NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem"

PowerShell

$env:NODE_EXTRA_CA_CERTS="absolute/path/to/your/certificates.pem"

Enums

The following tables enumerate values required in documented scenarios:

Two-step Login Methods

Used to specify which Two-step Login method to use when logging in:

Item Types

Used with the create command to specify a Vault item type:

Login URI Match Types

Used with the create and edit commands to specify URI match detection behavior:

Field Types

Used with the create and edit commands to configure custom fields:

Organization User Types

Indicates a user’s type:

Organization User Statuses

Indicates a user’s status within the Organization: