Managing key-value secrets with Vault CLI

If you already use HashiCorp Vault, you can use the command-line interface (CLI) to interact with IBM Cloud® Secrets Manager to manage your key-value secrets. All operations follow the guidelines that are available for the Vault CLI.

Before you get started, configure the Vault CLI so that you're able to access your Secrets Manager instance by using Vault commands. To learn more about using the Vault CLI, check out the Vault documentation.

To use the standard CLI for Secrets Manager, check out the Secrets Manager CLI reference.

Create or update a key-value secret

Create a version of a key-value secret.

vault kv put [-format=FORMAT] ibmcloud/kv/SECRET_NAME [KEY_VALUE_PAIRS]

Create a version of a key-value secret in a custom group.

vault kv put [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME [KEY_VALUE_PAIRS]

Prerequisites

You need the Writer service role to create a key-value secret.

Command options

-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Create or update the payload of a key-value secret.

vault kv put ibmcloud/kv/example-kv-secret key1=value1 key2=value2

Create or update the payload of a key-value secret in a custom group.

vault kv put ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/example-kv-secret key1=value1 key2=value2

Output

The command to create a new version of a kv secret returns the following output:

Key              Value
---              -----
created_time     2022-03-08T18:32:43.610242127Z
deletion_time    n/a
destroyed        false
version          2

Read a version of a key-value secret

Get a version of a key-value secret. A successful request returns the secret data that is associated with the specified version of your secret, along with other metadata.

vault kv get [-version=VERSION] [-format=FORMAT] ibmcloud/kv/SECRET_NAME

Get a version of a key-value secret in a custom group.

vault kv get [-version=VERSION] [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Reader or Writer service role to read versions of key-value secrets.

Command options

-version: The version that you want to read. If omitted, the latest version is returned.
-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Read a version of a key-value secret.

vault kv get -version=1 ibmcloud/kv/my-test-kv-secret

Read a version of a key-value secret in a custom group.

vault kv get -version=1 ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/my-test-kv-secret

Output

The command to read a version of a kv secret returns the following output:

====== Metadata ======
Key              Value
---              -----
created_time     2022-03-04T17:08:34.406336489Z
deletion_time    n/a
destroyed        false
version          1

==== Data ====
Key     Value
---     -----
key1    value1

Delete the latest version of a key-value secret

Delete the latest version of a key-value secret. You can undo the deletion by calling the undelete command.

vault kv delete [-format=FORMAT] ibmcloud/kv/SECRET_NAME

Delete the latest version of a key-value secret in a custom group.

vault kv delete [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Manager service role to delete key-value secrets.

Command option

-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Delete the latest version of a key-value secret.

vault kv delete -format=json ibmcloud/kv/my-test-kv-secret

Delete the latest version of a key-value secret in a custom group.

vault kv delete -format=json ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/my-test-kv-secret

Output

The command to delete the latest version of a kv secret returns no output.

Delete specified versions of a key-value secret

Delete the specified versions of a key-value secret. You can undo the deletion by calling the undelete command.

vault kv delete [-versions=VERSIONS] [-format=FORMAT] ibmcloud/kv/SECRET_NAME

Delete the specified versions of a key-value secret in a custom group.

vault kv delete [-versions=VERSIONS] [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Manager service role to delete key-value secrets.

Command options

-versions: The versions that you want to delete.
-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Delete specified versions of a key-value secret.

vault kv delete -versions=2 ibmcloud/kv/my-test-kv-secret

Delete specified versions of a key-value secret in a custom group.

vault kv delete -versions=2 ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/my-test-kv-secret

Output

The command to delete specified versions of a kv secret returns no output.

Undelete a key-value secret

Restore a previously deleted version of a key-value secret.

vault kv undelete [-versions=VERSIONS] [-format=FORMAT] ibmcloud/kv/SECRET_NAME

Restore a previously deleted version of a key-value secret in a custom group.

vault kv undelete [-versions=VERSIONS] [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Manager service role to restore secrets.

Command options

-versions: The versions that you want to delete.
-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Undelete specified versions of a key-value secret.

vault kv undelete -versions=2 ibmcloud/kv/my-test-kv-secret

Undelete specified versions of a key-value secret.

vault kv undelete -versions=2 ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/my-test-kv-secret

Output

The command to undelete specified versions of a kv secret returns the following output:

Success! Data written to: ibmcloud/kv/undelete/my-test-kv-secret

Destroy versions of a secret

Destroy specified versions of a key-value secret permanently. To soft delete versions of a secret instead, use the delete specified versions command.

vault kv destroy [-versions=VERSIONS] [-format=FORMAT] ibmcloud/kv/SECRET_NAME

Destroy the specified versions of a key-value secret in a custom group.

vault kv destroy [-versions=VERSIONS] [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Manager service role to delete secrets.

Command options

-versions: The versions that you want to destroy.
-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Delete permanently specified versions of a key-value secret.

vault kv destroy -versions=2 ibmcloud/kv/my-test-kv-secret

Delete permanently specified versions of a key-value secret in a custom group.

vault kv destroy -versions=2 ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/my-test-kv-secret

Output

The command to destroy versions of a kv secret returns the following output:

Success! Data written to: ibmcloud/kv/undelete/my-test-kv-secret

Create or update metadata key-value secret

Create or update metadata of a key-value secret.

vault kv metadata put [-format=FORMAT] [METADATA_KEY_VALUE_PAIRS] ibmcloud/kv/SECRET_NAME

Create or update metadata of a key-value secret in a custom group.

vault kv metadata put [-format=FORMAT] [METADATA_KEY_VALUE_PAIRS] ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Writer service role to create a key-value secret.

Command options

-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Create or update the payload of a key-value secret.

vault kv metadata put -custom-metadata=key1=value1 -custom-metadata=key2=value2 ibmcloud/kv/mysecret

Create or update the payload of a key-value secret in a custom group.

vault kv metadata put -custom-metadata=key1=value1 -custom-metadata=key2=value2 ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/mysecret

Output

The command to create a new version of a kv secret returns the following output:

Key              Value
---              -----
created_time     2022-03-08T18:32:43.610242127Z
deletion_time    n/a
destroyed        false
version          2

Read metadata of key-value secret

Get a key-value secret's metadata.

vault kv metadata get ibmcloud/kv/SECRET_NAME

Get a key-value secret's metadata in a custom group.

vault kv metadata get ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Reader or Writer service role to read the metadata of key-value secrets.

Command options

-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Read the metadata of a key-value secret.

vault kv metadata get ibmcloud/kv/my-test-kv-secret

Read the metadata of a key-value secret in a custom group.

vault kv metadata get ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/my-test-kv-secret

Output

The command to read the metadata of a kv secret returns the following output:

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2022-03-04T17:08:34.406336489Z
current_version         3
custom_metadata         map[key1:value1 key2:value2]
delete_version_after    0s
max_versions            10
oldest_version          0
updated_time            2022-03-08T20:06:39.585190049Z

====== Version 1 ======
Key              Value
---              -----
created_time     2022-03-04T17:08:34.406336489Z
deletion_time    n/a
destroyed        true

====== Version 2 ======
Key              Value
---              -----
created_time     2022-03-08T18:32:43.610242127Z
deletion_time    2022-03-08T20:05:08.850704454Z
destroyed        false

====== Version 3 ======
Key              Value
---              -----
created_time     2022-03-08T20:06:39.585190049Z
deletion_time    n/a
destroyed        false

Delete the metadata and all versions of a key-value secret

Delete the metadata and all version data of a specified key-value secret permanently. All version history is removed when you use this command.

vault kv metadata delete ibmcloud/kv/SECRET_NAME

vault kv metadata delete ibmcloud/kv/GROUP_ID/SECRET_NAME

Prerequisites

You need the Manager service role to delete the metadata of key-value secrets.

Command options

-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Delete permanently the data and metadata of a key-value secret.

vault kv metadata delete ibmcloud/kv/my-test-kv-secret

Delete permanently the data and metadata of a key-value secret in a custom secret group.

vault kv metadata delete ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/my-test-kv-secret

Output

The command to delete the metadata of a kv secret returns the following output:

Success! Data deleted (if it existed) at: ibmcloud/kv/metadata/my-test-kv-secret

List key names of a key-value secret

Get a list of key names of a key-value secret. Do not encode sensitive information in key names. The values of the keys are not accessible by using this command.

vault kv list ibmcloud/kv

List the key names of key-value secrets that are stored in a custom secret group.

vault kv list ibmcloud/kv/GROUP_ID

Prerequisites

You need the Reader or Writer service role to read the key names of key-value secrets.

Command options

-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

List the key names of key-value secrets that are stored in the default secret group.

vault kv list ibmcloud/kv

List the key names of key-value secrets that are stored in a custom secret group.

vault kv list ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8

Output

The command to list key names of a kv secret returns the following output:

Keys
----
my-updated-kv-secret

Patch a key-value secret

Patch a version of a key-value secret.

vault kv patch [-format=FORMAT] ibmcloud/kv/SECRET_NAME [KEY_VALUE_PAIRS]

Create a version of a key-value secret in a custom group.

vault kv patch [-format=FORMAT] ibmcloud/kv/GROUP_ID/SECRET_NAME [KEY_VALUE_PAIRS]

Prerequisites

You need the Writer service role to create a key-value secret.

Command options

-format: Prints the output in the format that you specify. Valid formats are table, json, and yaml. The default is table. You can also set the output format by using the VAULT_FORMAT environment variable.

Example

Create or update the payload of a key-value secret.

vault kv patch ibmcloud/kv/example-kv-secret key1=value1 key2=value2

Create or update the payload of a key-value secret in a custom group.

vault kv patch ibmcloud/kv/9426e546-83de-4da5-9631-d70c993186c8/example-kv-secret key1=value1 key2=value2

Output

The command to create a new version of a kv secret returns the following output:

Key              Value
---              -----
created_time     2022-03-08T18:32:43.610242127Z
deletion_time    n/a
destroyed        false
version          2