Secrets Manager CLI

The Secrets Manager command-line interface (CLI) is a powerful tool for retrieving and injecting your secrets. The Secrets Manager CLI can be used to organize your vault with create, delete, edit, and list your secrets and projects. The Secrets Manager CLI has two run options:

Standard usage

Docker usage

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

bws --help, -h

Download and install

The CLI can be used cross-platform on Windows, macOS, and Linux distributions. To download and install the Secrets Manager CLI you can use the install scripts:

Mac

curl https://bws.bitwarden.com/install | sh

Windows

iwr https://bws.bitwarden.com/install | iex

Linux

curl https://bws.bitwarden.com/install | sh

Manual

1. Download the appropriate version for your operating system from github.com/bitwarden/sdk/releases.
2. Extract the downloaded file.
3. Move the bws executable to a directory in your system’s PATH. For example:

   iwr sudo mv path/to/extracted/bws /usr/local/bin/bws

4. Verify the installation:

   bws --version

Note

When using the downloaded native executable, you’ll need to add the executable to your PATH or else run commands from the directory the file is downloaded to.

Run with Docker

The Secrets Manager CLI can also run with Docker. An example Dockerfile can be located in the Bitwarden Secrets Manager SDK repository.

You can run the Docker image with the following:

docker run --rm -it bitwarden/bws --help

Note

If you want to use identical config file paths on your host and in the container, the parent directory must exist on both.

Authentication

The Secrets Manager CLI can be logged in to using an access token generated for a particular machine account. This means that only secrets and projects which the machine account has access to may be interacted with using the CLI. There are a few ways you can authenticate a CLI session:

Environment Variables

You can authenticate a CLI session by saving an environment variable BWS_ACCESS_TOKEN with the value of your access token, for example:

export BWS_ACCESS_TOKEN=0.48c78342-1635-48a6-accd-afbe01336365.C0tMmQqHnAp1h0gL8bngprlPOYutt0:B3h5D+YgLvFiQhWkIq6Bow==

Inline

You can authenticate individual CLI requests using the -t, --access-token flag with any individual command, for example:

bws secret list --access-token 0.48c78342-1635-48a6-accd-afbe01336365.C0tMmQqHnAp1h0gL8bngprlPOYutt0:B3h5D+YgLvFiQhWkIq6Bow==

Warning

If your workflow uses many separate sessions (where each use of an access token to authenticate constitutes a “session”) to make requests from the same IP address in a short span of time, you may encounter rate limits.