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 organize your vault with create
, delete
, edit
, and list
your secrets and projects.
The Secrets Manager CLI is self-documented. From the command line, learn more about the available commands using:
bws --help, -h
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==
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==
注意
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.
Commands are used to interact with the Secrets Manager CLI. Secrets and Projects can be read or written to depending on the permissions given to your specific access token. For additional details regarding the commands available for secret
and project
, use:
bws secret --help
bws project --help
備考
As of the Secrets Manager version 0.3.0, CLI syntax has been changed. The command to list secrets, for example has changed from bws list secrets
to bws secret list
.
The old syntax will temporarily remain supported in the Secrets Manager CLI. If you are not sure what version of the Secrets Manager CLI you're using, enter bws --version
.
The secret
command is used to access, manipulate, and create secrets. As with all commands, secrets and projects outside your access token's scope of access cannot be read or written-to.
Use bws secret create
to create a new secret. This command requires a KEY
, VALUE
, and PROJECT_ID
:
bws secret create <KEY> <VALUE> <PROJECT_ID>
Optionally, you can add a note using the --note <NOTE>
option. For example:
bws secret create SES_KEY 0.982492bc-7f37-4475-9e60 f588b2f2-4780-4a78-be2a-b02d014d622f --note "API Key for AWS SES"
This command, by default, will return a JSON object and save the secret to Secrets Manager. You can alter the output format using the --output
flag (learn more).
{
"object": "secret",
"id": "be8e0ad8-d545-4017-a55a-b02f014d4158",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"projectId": "e325ea69-a3ab-4dff-836f-b02e013fe530",
"key": "SES_KEY",
"value": "0.982492bc-7f37-4475-9e60",
"note": "API Key for AWS SES",
"creationDate": "2023-06-28T20:13:20.643567Z",
"revisionDate": "2023-06-28T20:13:20.643567Z"
}
Use bws secret delete
to delete one or more secrets designated by the SECRET_IDS
.
bws secret delete <SECRET_IDS>
To delete a single secret with the id
be8e0ad8-d545-4017-a55a-b02f014d4158
:
bws secret delete be8e0ad8-d545-4017-a55a-b02f014d4158
For multiple secrets where the ids
are 382580ab-1368-4e85-bfa3-b02e01400c9f
and 47201c5c-5653-4e14-9007-b02f015b2d82
:
bws secret delete 382580ab-1368-4e85-bfa3-b02e01400c9f 47201c5c-5653-4e14-9007-b02f015b2d82
Output:
1 secret deleted successfully.
To edit a secret, the following structure will apply changes to the chosen value. From the CLI this commands can edit the secret KEY
, VALUE
, NOTE
, or PROJECT_ID
.
bws secret edit <SECRET_ID> --key <KEY> --value <VALUE> --note <NOTE> --project-id <PROJECT_ID>
For example, if you wish to add a note to an existing secret:
bws secret edit be8e0ad8-d545-4017-a55a-b02f014d4158 --note "I am adding a note"
備考
Include quotation marks around the string when editing a NOTE
containing spaces.
To edit multiple fields where SES_KEY2
is the new key
and 0.1982492bc-7f37-4475-9e60
is the new value
:
bws secret edit be8e0ad8-d545-4017-a55a-b02f014d4158 --key SES_KEY2 --value 0.1982492bc-7f37-4475-9e60
Output:
{
"object": "secret",
"id": "be8e0ad8-d545-4017-a55a-b02f014d4158",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"projectId": "e325ea69-a3ab-4dff-836f-b02e013fe530",
"key": "SES_KEY2",
"value": "0.1982492bc-7f37-4475-9e60",
"note": "I am adding a note",
"creationDate": "2023-06-28T20:13:20.643567Z",
"revisionDate": "2023-06-28T20:45:37.46232Z"
}
Use bws secret get
to retrieve a specific secret:
bws secret get <SECRET_ID>
By default, this command will retrieve the secret object with the SECRET_ID
.
bws secret get be8e0ad8-d545-4017-a55a-b02f014d4158
By default, get
will return objects as a JSON array, as shown in the following example. You can alter the output format using the --output
flag (learn more).
{
"object": "secret",
"id": "be8e0ad8-d545-4017-a55a-b02f014d4158",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"projectId": "e325ea69-a3ab-4dff-836f-b02e013fe530",
"key": "SES_KEY",
"value": "0.982492bc-7f37-4475-9e60",
"note": "",
"creationDate": "2023-06-28T20:13:20.643567Z",
"revisionDate": "2023-06-28T20:13:20.643567Z"
}
To list the secrets the service account can access, use the following command:
bws secret list
You can also list only the secrets in a specific project by using the following command, where e325ea69-a3ab-4dff-836f-b02e013fe530
represents a project identifier:
bws secret list e325ea69-a3ab-4dff-836f-b02e013fe530
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": "382580ab-1368-4e85-bfa3-b02e01400c9f",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"projectId": "e325ea69-a3ab-4dff-836f-b02e013fe530",
"key": "Repository 1",
"value": "1234567ertthrjytkuy",
"note": "Main Repo",
"creationDate": "2023-06-27T19:25:15.822004Z",
"revisionDate": "2023-06-27T19:25:15.822004Z"
},
{
"object": "secret",
"id": "be8e0ad8-d545-4017-a55a-b02f014d4158",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"projectId": "e325ea69-a3ab-4dff-836f-b02e013fe530",
"key": "SES_KEY",
"value": "0.982492bc-7f37-4475-9e60",
"note": "",
"creationDate": "2023-06-28T20:13:20.643567Z",
"revisionDate": "2023-06-28T20:13:20.643567Z"
}
]
The project command is used to access, manipulate, and create projects. The scope of access assigned to your service account will determine what actions can be completed with the project
command.
備考
Projects can be created by a service account with read-only access. However, existing projects that were not created by the service account cannot be edited without read and write access.
Use bws project create
to create a new project. This command requires a NAME
.
bws project create <NAME>
In this example, a project will be created with the name My project
.
bws project create "My project"
By default, bws project create
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": "1c80965c-acb3-486e-ac24-b03000dc7318",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"name": "My project",
"creationDate": "2023-06-29T13:22:37.942559Z",
"revisionDate": "2023-06-29T13:22:37.942559Z"
}
Use bws project delete
to delete one or more projects designated by the PROJECT_IDS
.
bws project delete <PROJECT_IDS>
For a single project where f1fe5978-0aa1-4bb0-949b-b03000e0402a
represents the PROJECT_ID
:
bws project delete f1fe5978-0aa1-4bb0-949b-b03000e0402a
For multiple projects where 1c80965c-acb3-486e-ac24-b03000dc7318
and f277fd80-1bd2-4532-94b2-b03000e00c6c
represent the PROJECT_IDS
:
bws project delete 1c80965c-acb3-486e-ac24-b03000dc7318 f277fd80-1bd2-4532-94b2-b03000e00c6c
Output:
1 project deleted successfully.
Using the edit
command you can change the name of a project with the following input:
bws project edit <PROJECT_ID> --name <NEW_NAME>
For example, this command will change the project name to My project 2
.
bws project edit 1c80965c-acb3-486e-ac24-b03000dc7318 --name "My project 2"
By default, bws project edit
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": "1c80965c-acb3-486e-ac24-b03000dc7318",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"name": "My project 2",
"creationDate": "2023-06-29T13:22:37.942559Z",
"revisionDate": "2023-06-29T13:31:07.927829Z"
}
The get
command retrieves a specific project 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.
bws project get <PROJECT_ID>
To get a specific project, use the following command where e325ea69-a3ab-4dff-836f-b02e013fe530 represents a PROJECT_ID
:
bws project get e325ea69-a3ab-4dff-836f-b02e013fe530
By default, get
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": "e325ea69-a3ab-4dff-836f-b02e013fe530",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"name": "App 1",
"creationDate": "2023-06-27T19:24:42.181607Z",
"revisionDate": "2023-06-27T19:24:42.181607Z"
}
To list the projects this service account has access to, use the following command:
bws project list
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": "e325ea69-a3ab-4dff-836f-b02e013fe530",
"organizationId": "10e8cbfa-7bd2-4361-bd6f-b02e013f9c41",
"name": "App 1",
"creationDate": "2023-06-27T19:24:42.181607Z",
"revisionDate": "2023-06-27T19:24:42.181607Z"
}.
...
]
備考
While the functionality described below is offered by the CLI, some is intended to be used for self-hosting which is not currently available.
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
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:
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
Once created, you can use that profile with other commands to route requests to the specified server, for example:
bws secret get 2863ced6-eba1-48b4-b5c0-afa30104877a --profile dev
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
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
Once created, you can use that profile with other commands to route requests to the specified server, for example:
bws secret get 2863ced6-eba1-48b4-b5c0-afa30104877a --config-file ~/.bws/alt_config --profile alt_dev
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 secret get 2863ced6-eba1-48b4-b5c0-afa30104877a --output yaml
will 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
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 secret list --access-token 0.48c78342-1635-48a6-accd-afbe01336365.C0tMmQqHnAp1h0gL8bngprlPOYutt0:B3h5D+YgLvFiQhWkIq6Bow==
Use the --profile
option with the list
or get
commands to specify which profile to use, for example:
bws secret get 2863ced6-eba1-48b4-b5c0-afa30104877a --profile dev
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 secret get 2863ced6-eba1-48b4-b5c0-afa30104877a --config-file ~/.bws/alt_config --profile alt_dev
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
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.