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:
--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.
The CLI can be used cross-platform on Windows, macOS, and Linux distributions. To download and install the Bitwarden CLI:
Natively packaged versions of the CLI are available for each platform and have no dependencies. Download using one of these links:
In UNIX systems, you might get a
Permission denied message. If you do, grant permission by running:
chmod +x </path/to/executable>
If you have Node.js installed on your system, you can install the CLI using NPM. Installing with NPM is the simplest way to keep your installation up-to-date and should be the preferred method for those already comfortable with NPM:
npm install -g @bitwarden/cli
View the package on npmjs.org.
To install with Chocolatey:
choco install bitwarden-cli
View the package on community.chocolatey.org.
To install with snap:
sudo snap install bw
View the package on snapcraft.io.
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:
No matter which option you use, always be sure to use the
bw lock or
bw logout commands when you're finished.
Logging in using email and master password uses your master password and can therefore string together the
unlock commands to authenticate your identity and decrypt your vault in tandem. Using an API key or SSO will require you to follow-up the
login command with an explicit
bw unlock if you will be working with vault data directly.
This is because your master password is the source of the key needed to decrypt vault data. There are, however, a few commands that do not require your vault to be decrypted, including
Logging in with email and password is recommended for interactive sessions. To log in with email and password:
You can string these factors together into a single command as in the following example, however this isn't recommended for security reasons:
bw login [email] [password] --method <method> --code <code>
See Enums for two-step login
Getting prompted for additional authentication or getting a
Your authentication request appears to be coming from a bot. error? Use your API Key
client_secret to answer the authentication challenge. Learn more.
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_secret. Once your session is authenticated using these values, you can use the
unlock command. Learn more.
If your organization requires SSO, you can still use
--apikey to log in to the CLI.
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.
|Environment Variable Name||Required Value|
Logging in with SSO is recommended if an organization requires SSO authentication. To log in with SSO:
bw login --sso
If your organization requires SSO, you may alternatively
use --apikey to log in to the CLI.
Unlocking your vault generates a session key which acts as a decryption key used to interact with data in your vault. The session key must be used to perform any command that touches vault data (for example,
edit). Session keys are valid until invalidated using
bw lock or
bw logout, however they will not persist if you open a new terminal window. Generate a new session key at any time using:
When you're finished, always end your session using the
bw lock command.
You can use the
--passwordenv <passwordenv> or
--passwordfile <passwordfile> options with
bw unlock to retrieve your master password rather than enter it manually, for example:
The following will look for an environment variable
BW_PASSWORDis non-empty and has correct values, the CLI will successfully unlock and return a session key:
bw unlock --passwordenv BW_PASSWORD
The following 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:
bw unlock --passwordfile ~/Users/Me/Documents/mp.txt
If you use the
--passwordfile option, protect your password file by locking access down to only the user who needs to run
bw unlock and only providing read access to that user.
When you unlock your vault using
bw login with email and password or
bw unlock, the CLI will return both an
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 list items --session "5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w=="
When you're finished, always end your session using the
bw lock or
bw logout commands. This will invalidate the active session key.
create command creates a new object (
attachment, and more) in your vault:
bw create (item|attachment|folder|org-collection) <encodedJson> [options]
create command takes encoded JSON. A typical workflow for creating an object might look something like:
get templatecommand (see details) to output the appropriate JSON template for the object type.
Use a command-line JSON processor like jq to manipulate the outputted template as required.
encodecommand (see details) to encode the manipulated JSON.
createcommand to create an object from the encoded JSON.
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
Upon successful creation, the newly created object will be returned as JSON.
create other item types
For example, the following command will create a secure note:
bw get template item | jq '.type = 2 | .secureNote.type = 0 | .notes = "Contents of my Secure Note." | .name = "My Secure Note"' | bw encode | bw create item
Notice in the above example that Secure Notes require a sub-template (
.secureNote.type). You can view Item type sub-templates using
bw get template (see here for details).
create attachment command attaches a file to an existing item.
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
If you don’t know the exact
itemid you want to use, use
bw get item <search-term> to return the item (see details), including its
get command retrieves a single object (
password, and more) from your vault:
bw get (item|username|password|uri|totp|exposed|attachment|folder|collection|organization|org-collection|template|fingerprint) <id> [options]
get command takes an item
id or string for its argument. If you use a string (for example, anything other than an exact
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 command can only return one result, so you should use specific search terms. If multiple results are found, the CLI will return an error.
get attachment command downloads a file attachment: