Password Manager 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
Text Copied!
Or, pass --help
as an option on any bw
command to see available options and examples:
bw list --help bw move --help
Text Copied!
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:
tip
In UNIX systems, you might get a Permission denied
message. If you do, grant permission by running:
chmod +x </path/to/executable>
Text Copied!
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
Text Copied!
View the package on npmjs.org.
To install with Chocolatey:
choco install bitwarden-cli
Text Copied!
View the package on community.chocolatey.org.
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.
tip
Logging in using email and master password uses your master password and can therefore string together the login
and 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 config
, encode
, generate
, update
, and status
.
Logging in with email and password is recommended for interactive sessions. To log in with email and password:
bw login
Text Copied!
This will initiate a prompt for your Email Address, Master Password, and (if enabled) at 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 isn't recommended for security reasons:
bw login [email] [password] --method <method> --code <code>
Text Copied!
See Enums for two-step login <method>
values.
tip
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
Text Copied!
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.
tip
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 |
---|---|
BW_CLIENTID |
|
BW_CLIENTSECRET |
|
Logging in with SSO is recommended if an organization requires SSO authentication. To log in with SSO:
bw login --sso
Text Copied!
This will initiate the SSO authentication flow in your web browser. Once your session is authenticated, you can use the unlock
command. Learn more.
tip
If your organization requires SSO, you may alternatively use --apikey
to log in to the CLI.
Like using account switching on other Bitwarden apps, the CLI has the ability to log in to multiple accounts simultaneously using the BITWARDENCLI_APPDATA_DIR
environment variable pointing to the location of a bw
configuration file, usually named data.json
. You can, for example, set aliases in a .bashrc
profile for two separate configurations:
alias bw-personal="BITWARDENCLI_APPDATA_DIR=~/.config/Bitwarden\ CLI\ Personal /path/to/bw $@" alias bw-work="BITWARDENCLI_APPDATA_DIR=~/.config/Bitwarden\ CLI\ Work /path/to/bw $@"
Text Copied!
Using this example, you could then use login to two accounts by running first source /path/to/.bashrc
, followed by bw-personal login
and bw-work login
.
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'll be working with vault data directly.
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, list
, get
, 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:
bw unlock
Text Copied!
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_PASSWORD
. IfBW_PASSWORD
is non-empty and has correct values, the CLI will successfully unlock and return a session key:bw unlock --passwordenv BW_PASSWORD
Text Copied!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
Text Copied!
注意
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
Text Copied!
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=="
Text Copied!
tip
When you're finished, always end your session using the bw lock
or bw logout
commands. This will invalidate the active session key.
The create
command creates a new object (item
, attachment
, and more) in your vault:
bw create (item|attachment|folder|org-collection) <encodedJson> [options]
Text Copied!
The create
command takes encoded JSON. A typical workflow for creating an object might look something like:
Use the
get template
command (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.
Use the
encode
command (see details) to encode the manipulated JSON.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
Text Copied!
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
Text Copied!
Upon successful creation, the newly created object will be returned as JSON.
create other item types
The create command defaults to creating a login item, but you can use a command-line JSON processor like jq to change a .type=
attribute to create other item types:
Name | Value |
---|---|
Login |
|
Secure note |
|
Card |
|
Identity |
|
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
Text Copied!
備考
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
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
Text Copied!
tip
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 id
.
The get
command retrieves a single object (item
, username
, password
, and more) from your vault:
bw get (item|username|password|uri|totp|exposed|attachment|folder|collection|organization|org-collection|template|fingerprint) <id> [options]
Text Copied!
The get
command takes an item id
or string for its argument. If you use a string (for example, 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
Text Copied!
備考
The 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
The get attachment
command downloads a file attachment:
bw get attachment <filename> --itemid <id>
Text Copied!
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/
Text Copied!
備考
When using --output
, the path must end a forward slash (/
) to specify a directory or a filename (/Users/myaccount/Pictures/photo.png
).
get notes
The get notes
command retrieves the note for any vault item:
bw get notes <id>
Text Copied!
The get notes
command takes an exact item id
or string. If you use a string (for example, anything other than an exact id
), get notes
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
Text Copied!
get template
The get template
command returns the expected JSON formatting for an object (item
, item.field
, item.login
, and more):
bw get template (item|item.field|item.login|item.login.uri|item.card|item.identity|item.securenote|folder|collection|item-collections|org-collection)
Text Copied!
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
Text Copied!
備考
Any item.xxx
template should be used as a sub-object to an item
template, for example:
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
Text Copied!
The edit
command edits an object (item
, item-collections
, etc.) in your vault:
bw edit (item|item-collections|folder|org-collection) <id> [encodedJson] [options]
Text Copied!
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:
Use the
get
command (see details) to output the object to edit.Use a command-line JSON processor like jq to manipulate the outputted object as required.
Use the
encode
command (see details) to encode the manipulated JSON.Use the
edit
command (including the objectid
) to edit the object.
For example, to edit the password of a login item:
bw get item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328 | jq '.login.password="newp@ssw0rd"' | bw encode | bw edit item 7ac9cae8-5067-4faf-b6ab-acfd00e2c328