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, -h
Text Copied!
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.
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!
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 secrets
Text 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-acfd01232bbb
Text 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 projects
Text 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!
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-aeaf0102f0ff
Text 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-acfd01232bbb
Text 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!
備考
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.com
Text 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 dev
Text 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 dev
Text 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_config
Text 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_dev
Text 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_dev
Text Copied!
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.470702Z
Text Copied!
Output can further be customized by indicated whether you would like colorized output. Available values for this option are yes
, no
, and auto
.
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!
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 dev
Text Copied!
Refer to the config
command (here) for help understanding and setting up alternate profiles.
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_dev
Text Copied!
Refer to the config
command (here) for help understanding and setting up alternate config files and profiles.
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.com
Text Copied!
This option will override any URLS configured via the config
command (see here).
Use this option to print help for any given bws
command.
Use this option to print the version of the bws
client you're using.