Secrets ManagerDeveloper Tools

Secrets Manager CLI

The Secrets Manager command-line interface (CLI) is a powerful tool for retrieving and injecting your secrets. As of beta launch, the CLI can primarily be used to list and get secrets and projects from your vault.

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

bws --help, -hText Copied!

Download and install

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

Download the Secrets Manager CLI from https://github.com/bitwarden/sdk/releases.

Authentication

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

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==Text Copied!

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

bws list secrets --access-token 0.48c78342-1635-48a6-accd-afbe01336365.C0tMmQqHnAp1h0gL8bngprlPOYutt0:B3h5D+YgLvFiQhWkIq6Bow==Text Copied!

Commands

list

The list command retrieves an array of objects which the logged-in service account can access from your vault. Objects in your vault that the service account does not have access to will not be listed.

list secrets

To list the secrets the service account can access, use the following command:

bws list secretsText Copied!

By default, list will return objects as a JSON array, as in the following example. You can alter the output format using the --output flag (learn more).

[
  {
    "object": "secret",
    "id": "fc3a93f4-2a16-445b-b0c4-aeaf0102f0ff",
    "organizationId": "9292592f-1efe-43fa-8947-acfd01232bb5",
    "projectId": "80b55c29-5cc8-42eb-a898-acfd01232bbb",
    "key": "Stripe API Key",
    "value": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe",
    "note": "For Stripe billing & payments",
    "creationDate": "2023-02-08T15:46:14.114158Z",
    "revisionDate": "2023-02-24T19:29:19.158506Z"
  },
  ...
]Text Copied!

list secrets {projectId}

You can also list only the secrets in a specific project by using the following command, where 80b55c29-5cc8-42eb-a898-acfd01232bbb represents a project identifier:

bws list secrets 80b55c29-5cc8-42eb-a898-acfd01232bbbText Copied!

By default, list will return objects as a JSON array, as in the following example. You can alter the output format using the --output flag (learn more).

[
  {
    "object": "secret",
    "id": "fc3a93f4-2a16-445b-b0c4-aeaf0102f0ff",
    "organizationId": "9292592f-1efe-43fa-8947-acfd01232bb5",
    "projectId": "80b55c29-5cc8-42eb-a898-acfd01232bbb",
    "key": "Stripe API Key",
    "value": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe",
    "note": "For Stripe billing & payments",
    "creationDate": "2023-02-08T15:46:14.114158Z",
    "revisionDate": "2023-02-24T19:29:19.158506Z"
  },
  ...
]Text Copied!

list projects

To list the projects this service account has access to, use the following command:

bws list projectsText Copied!

By default, list will return objects as a JSON array, as in the following example. You can alter the output format using the --output flag (learn more).

[
  {
    "object": "project",
    "id": "80b55c29-5cc8-42eb-a898-acfd01232bbb",
    "organizationId": "9292592f-1efe-43fa-8947-acfd01232bb5",
    "name": "My Project",
    "creationDate": "2023-02-08T15:39:52.943244Z",
    "revisionDate": "2023-02-08T15:39:52.943244Z"
  },
  ...
]Text Copied!

get

The get command retrieves a specific object which the logged-in service account can access from your vault. Objects in your vault that the service account does not have access to cannot be retrieved.

get secret {secretId}

To get a specific secret, use the following command where fc3a93f4-2a16-445b-b0c4-aeaf0102f0ff represents a secret identifier:

bws get secret fc3a93f4-2a16-445b-b0c4-aeaf0102f0ffText Copied!

By default, list will return objects as a JSON array, as in the following example. You can alter the output format using the --output flag (learn more).

{
    "object": "secret",
    "id": "fc3a93f4-2a16-445b-b0c4-aeaf0102f0ff",
    "organizationId": "9292592f-1efe-43fa-8947-acfd01232bb5",
    "projectId": "80b55c29-5cc8-42eb-a898-acfd01232bbb",
    "key": "Stripe API Key",
    "value": "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe",
    "note": "For Stripe billing & payments",
    "creationDate": "2023-02-08T15:46:14.114158Z",
    "revisionDate": "2023-02-24T19:29:19.158506Z"
  }Text Copied!

get project {projectId}

To retrieve a specific project, use the following command where 80b55c29-5cc8-42eb-a898-acfd01232bbb represents a project identifier:

bws get project 80b55c29-5cc8-42eb-a898-acfd01232bbbText Copied!

By default, list will return objects as a JSON array, as in the following example. You can alter the output format using the --output flag (learn more).

{
  "object": "project",
  "id": "80b55c29-5cc8-42eb-a898-acfd01232bbb",
  "organizationId": "9292592f-1efe-43fa-8947-acfd01232bb5",
  "name": "My Project",
  "creationDate": "2023-02-08T15:39:52.943244Z",
  "revisionDate": "2023-02-08T15:39:52.943244Z"
}Text Copied!

config

note

While the functionality described below is offered by the CLI, some is intended to be used for self-hosting which is not available during the Secrets Manager beta.

The config command specifies server settings for the Secrets Manager CLI to use. Available settings include server-base, server-api, and server-identity, for example:

bws config server-base https://my_hosted_server.comText Copied!

When done this way, your specified server values will be saved to a default profile in a ~/.bws/config file. You can use subsequent options to create alternate profiles and config files:

config --profile

Use the --profile option with the config command to save specified server values to alternate profiles, for example:

bws config server-base http://other_hosted_server.com --profile devText Copied!

Once created, you can use that profile with other commands to route requests to the specified server, for example:

bws get secret 2863ced6-eba1-48b4-b5c0-afa30104877a --profile devText Copied!

config --config-file

Use the --config-file option with the config command to save specified server values to alternate config files, for example to save values to a default profile in a new config file:

bws config server-base http://third_hosted_server.com --config-file ~/.bws/alt_configText Copied!

You can chain --config-file with --profile to save values to alternate profiles in alternate config files, for example:

bws config server-base http://third_hosted_server.com --config-file ~/.bws/alt_config --profile alt_devText Copied!

Once created, you can use that profile with other commands to route requests to the specified server, for example:

bws get secret 2863ced6-eba1-48b4-b5c0-afa30104877a --config-file ~/.bws/alt_config --profile alt_devText Copied!

Options

-o, --output

By default, the Secrets Manager CLI will return a JSON object or array of JSON objects in response to commands. Output format can be altered to fits your needs using the -o, --output flag along with one of the following options:

json: Default. Output JSON.
yaml: Output YAML.
table: Output an ASCII table with keys as column headings.
tsv: Output tab-separated values with no keys.
none: Only output errors and warnings.

For example, the command bws get secret 2863ced6-eba1-48b4-b5c0-afa30104877a --output yaml would return the following:

object: secret
id: 2863ced6-eba1-48b4-b5c0-afa30104877a
organizationId: b8824f88-c57c-4a36-8b1a-afa300fe0b52
projectId: 1d0a63e8-3974-4cbd-a7e4-afa30102257e
key: Stripe API Key
value: osiundfpowubefpouwef
note: 'These are notes.'
creationDate: 2023-02-08T15:48:33.470701Z
revisionDate: 2023-02-08T15:48:33.470702ZText Copied!

-c, --color

Output can further be customized by indicated whether you would like colorized output. Available values for this option are yes, no, and auto.

--access-token

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

bws list secrets --access-token 0.48c78342-1635-48a6-accd-afbe01336365.C0tMmQqHnAp1h0gL8bngprlPOYutt0:B3h5D+YgLvFiQhWkIq6Bow==Text Copied!

--profile

Use the --profile option with the list or get commands to specify which profile to use, for example:

bws get secret 2863ced6-eba1-48b4-b5c0-afa30104877a --profile devText Copied!

Refer to the config command (here) for help understanding and setting up alternate profiles.

--config-file

Use the --config-file option with the --profile option and list or get commands to specify which profile from which configuration file to use, for example:

bws get secret 2863ced6-eba1-48b4-b5c0-afa30104877a --config-file ~/.bws/alt_config --profile alt_devText Copied!

Refer to the config command (here) for help understanding and setting up alternate config files and profiles.

--server-url

This option can be used to set the server URL that the CLI will send the request associated with a given command to, for example:

bws list secrets --server-url http://my_hosted_server.comText Copied!

This option will override any URLS configured via the config command (see here).

--help

Use this option to print help for any given bws command.

--version

Use this option to print the version of the bws client you're using.

Secrets Manager CLI

Download and install

Authentication

Commands

list

list secrets

list secrets {projectId}

list projects

get

get secret {secretId}

get project {projectId}

config

.css-qqykjf{margin-right:0.25rem;}.css-cddjr8{display:inline-block;font-family:bwi-font;margin-right:0.25rem;}note

config --profile

config --config-file

Options

-o, --output

-c, --color

--access-token

--profile

--config-file

--server-url

--help

--version

note