Home
DocumentationTutorialsTry Cloud!

kv

kv

The kv command groups subcommands for interacting with Vault's key/value secrets engine (both K/V Version 1 and K/V Version 2.

Syntax

Option flags for a given subcommand are provided after the subcommand, but before the arguments.

The path to where the secrets engine is mounted can be indicated with the -mount flag, such as vault kv get -mount=secret creds.

A flag provided but not defined: -mount error means you are using an older version of Vault before the mount flag syntax was introduced. Upgrade to at least Vault 1.11, or refer to previous versions of the docs which only use the old syntax to refer to the mount path.

Examples

Create or update the key named "creds" in the K/V Version 2 enabled at "secret" with the value "passcode=my-long-passcode":

$ vault kv put -mount=secret creds passcode=my-long-passcode
== Secret Path ==
secret/data/creds

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-15T20:14:17.107852Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Read this value back:

$ vault kv get -mount=secret creds
== Secret Path ==
secret/data/creds

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-15T20:14:17.107852Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

====== Data ======
Key         Value
---         -----
passcode    my-long-passcode

Get metadata for the key named "creds":

$ vault kv metadata get -mount=secret creds
=== Metadata Path ===
secret/metadata/creds

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2022-06-15T20:14:17.107852Z
current_version         1
custom_metadata         <nil>
delete_version_after    0s
max_versions            0
oldest_version          0
updated_time            2022-06-15T20:14:17.107852Z

====== Version 1 ======
Key              Value
---              -----
created_time     2022-06-15T20:14:17.107852Z
deletion_time    n/a
destroyed        false

Get a specific version of the key named "creds":

$ vault kv get -mount=secret -version=1 creds
== Secret Path ==
secret/data/creds

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-15T20:14:17.107852Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

====== Data ======
Key         Value
---         -----
passcode    my-long-passcode

Usage

Usage: vault kv <subcommand> [options] [args]

  # ...

Subcommands:
    delete               Deletes versions in the KV store
    destroy              Permanently removes one or more versions in the KV store
    enable-versioning    Turns on versioning for a KV store
    get                  Retrieves data from the KV store
    list                 List data or secrets
    metadata             Interact with Vault's Key-Value storage
    patch                Sets or updates data in the KV store without overwriting
    put                  Sets or updates data in the KV store
    rollback             Rolls back to a previous version of data
    undelete             Undeletes versions in the KV store

For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.

kv delete

The kv delete command deletes the data for the provided path in the key/value secrets engine. If using K/V Version 2, its versioned data will not be fully removed, but marked as deleted and will no longer be returned in normal get requests.

Examples

Delete the latest version of the key "creds":

$ vault kv delete -mount=secret creds
Success! Data deleted (if it existed) at: secret/creds

[K/V Version 2] Delete version 11 of key "creds":

$ vault kv delete -mount=secret -versions=11 creds
Success! Data deleted (if it existed) at: secret/data/creds

Usage

There are no flags beyond the standard set of flags included on all commands.

Command options

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

  • -versions ([]int: <required>) - The versions to be deleted. The versioned data will not be deleted, but it will no longer be returned in normal get requests.

NOTE: The -versions command option is only for K/V v2.

kv destroy

NOTE: This is a K/V Version 2 secrets engine command, and not available for Version 1.

The kv destroy command permanently removes the specified versions' data from the key/value secrets engine. If no key exists at the path, no action is taken.

Examples

Destroy version 11 of the key "creds":

$ vault kv destroy -mount=secret -versions=11 creds
Success! Data written to: secret/destroy/creds

Usage

There are no flags beyond the standard set of flags included on all commands.

Output options

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

  • -versions ([]int: <required>) - The versions to destroy. Their data will be permanently deleted.

kv enable-versioning

The kv enable-versioning command turns on versioning for an existing non-versioned key/value secrets engine (K/V Version 1) at its path.

Examples

This command turns on versioning for the K/V Version 1 secrets engine enabled at "secret".

$ vault kv enable-versioning secret
Success! Tuned the secrets engine at: secret/

Usage

There are no flags beyond the standard set of flags included on all commands.

Output options

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

kv get

The kv get command retrieves the value from K/V secrets engine at the given key name. If no key exists with that name, an error is returned. If a key exists with the name but has no data, nothing is returned.

Examples

Retrieve the data of the key "creds":

$ vault kv get -mount=secret creds
== Secret Path ==
secret/data/creds

======= Metadata =======
Key                Value
---                -----
created_time       2022-06-15T20:23:40.067093Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

====== Data ======
Key         Value
---         -----
passcode    my-long-passcode

If K/V Version 1 secrets engine is enabled at "secret", the output has no metadata since there is no versioning information associated with the data:

$ vault kv get -mount=secret creds
====== Data ======
Key         Value
---         -----
passcode    my-long-passcode

Return only the "creds" "passcode" key:

$ vault kv get -mount=secret -field=passcode creds
my-long-passcode

Usage

Output options

  • -field (string: "") - Print only the field with the given name. Specifying this option will take precedence over other formatting directives. The result will not have a trailing newline making it ideal for piping to other processes.

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

  • -version (int: 0) - Specifies the version to return. If not set the latest version is returned.

kv list

The kv list command returns a list of key names at the specified location. Folders are suffixed with /. The input must be a folder; list on a file will not return a value. Note that no policy-based filtering is performed on keys; do not encode sensitive information in key names. The values themselves are not accessible via this command.

Use this command to list all existing key names at a specific path.

Examples

List values under the key "my-app":

$ vault kv list -mount=secret my-app/
Keys
----
admin_creds
domain
eng_creds
qa_creds
release

Usage

There are no flags beyond the standard set of flags included on all commands.

Output options

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

kv metadata

NOTE: This is a K/V Version 2 secrets engine command, and not available for Version 1.

The kv metadata command has subcommands for interacting with the metadata and versions for the versioned secrets (K/V Version 2 secrets engine) at the specified path.

Usage

Usage: vault kv metadata <subcommand> [options] [args]

  # ...

Subcommands:
    delete    Deletes all versions and metadata for a key in the KV store
    get       Retrieves key metadata from the KV store
    put       Sets or updates key settings in the KV store

kv metadata delete

The kv metadata delete command deletes all versions and metadata for the provided key.

Examples

Deletes all versions and metadata of the key "creds":

$ vault kv metadata delete -mount=secret creds
Success! Data deleted (if it existed) at: secret/metadata/creds

kv metadata get

The kv metadata get command retrieves the metadata of the versioned secrets at the given key name. If no key exists with that name, an error is returned.

Examples

Retrieves the metadata of the key name, "creds":

$ vault kv metadata get -mount=secret creds
=== Metadata Path ===
secret/metadata/creds

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2019-06-28T15:53:30.395814Z
current_version         5
delete_version_after    0s
max_versions            0
oldest_version          0
updated_time            2019-06-28T16:01:47.40064Z

====== Version 1 ======
Key              Value
---              -----
created_time     2019-06-28T15:53:30.395814Z
deletion_time    n/a
destroyed        false

====== Version 2 ======
Key              Value
---              -----
created_time     2019-06-28T16:01:36.676912Z
deletion_time    n/a
destroyed        false

...

kv metadata put

The kv metadata put command can be used to create a blank key in the K/V v2 secrets engine or to update key configuration for a specified key.

Examples

Create a key in the K/V v2 with no data at the key "creds":

$ vault kv metadata put -mount=secret creds
Success! Data written to: secret/metadata/creds

Set the maximum number of versions to keep for the key "creds":

$ vault kv metadata put -mount=secret -max-versions=5 creds
Success! Data written to: secret/metadata/creds

NOTE: If not set, the backend’s configured max version is used. Once a key has more than the configured allowed versions the oldest version will be permanently deleted.

Require Check-and-Set for the key "creds":

$ vault kv metadata put -mount=secret -cas-required creds

NOTE: When check-and-set is required, the key will require the cas parameter to be set on all write requests. Otherwise, the backend’s configuration will be used.

Set the length of time before a version is deleted for the key "creds":

$ vault kv metadata put -mount=secret -delete-version-after="3h25m19s" creds

NOTE: If not set, the backend's configured Delete-Version-After is used. If set to a duration greater than the backend's, the backend's Delete-Version-After setting will be used. Any changes to the Delete-Version-After setting will only be applied to new versions.

Output options

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Subcommand options

  • -cas-required (bool: false) - If true the key will require the cas parameter to be set on all write requests. If false, the backend’s configuration will be used. The default is false.

  • -max-versions (int: 0) - The number of versions to keep per key. If not set, the backend’s configured max version is used. Once a key has more than the configured allowed versions the oldest version will be permanently deleted.

  • -delete-version-after (string:"0s") – Set the delete-version-after value to a duration to specify the deletion_time for all new versions written to this key. If not set, the backend's delete_version_after will be used. If the value is greater than the backend's delete_version_after, the backend's delete_version_after will be used. Accepts duration format strings.

  • -custom-metadata (string: "") - Specifies a key-value pair for the custom_metadata field. This can be specified multiple times to add multiple pieces of metadata.

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

kv patch

NOTE: This is a K/V Version 2 secrets engine command, and not available for Version 1.

The kv patch command writes the data to the given path in the K/V v2 secrets engine. The data can be of any type. Unlike the kv put command, the patch command combines the change with existing data instead of replacing them. Therefore, this command makes it easy to make a partial updates to an existing data.

Examples

If you wish to add an additional key-value (ttl=48h) to the existing data at the key "creds":

$ vault kv patch -mount=secret creds ttl=48h
== Secret Path ==
secret/data/creds

======= Metadata =======
Key              Value
---              -----
created_time     2019-06-06T16:46:22.090654Z
deletion_time    n/a
destroyed        false
version          6

NOTE: The kv put command requires both the existing data and the data you wish to add in order to accomplish the same result.

$ vault kv put -mount=secret creds ttl=48h passcode=my-long-passcode

The data can also be consumed from a file on disk by prefixing with the "@" symbol. For example:

$ vault kv patch -mount=secret creds @data.json

Or it can be read from stdin using the "-" symbol:

$ echo "abcd1234" | vault kv patch -mount=secret foo bar=-

Usage

Output options

  • -field (string: "") - Print only the field with the given name. Specifying this option will take precedence over other formatting directives. The result will not have a trailing newline making it ideal for piping to other processes.

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

  • -method (string: "patch") - Specifies the patch method to use. Valid methods are patch and rw. The patch method uses an HTTP PATCH request to apply the partial update. The rw method will fetch the secret's data, perform an in-memory update, and write the updated data.

  • -cas (int: 0) - Specifies the value to use for the Check-And-Set operation. This flag will only be used for the patch method. This flag is required if cas_required is set to true on either the secret or the engine's config. In order for a patch to be successful, -cas must be set to the current version of the secret. This flag will be ignored for the rw method. Instead, its value will be derived from fetching the current version of the secret.

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

kv put

The kv put command writes the data to the given path in the K/V secrets engine.

If working with K/V v2, this command creates a new version of a secret at the specified location. If working with K/V v1, this command stores the given secret at the specified location.

Regardless of the K/V version, if the value does not yet exist at the specified path, the calling token must have an ACL policy granting the "create" capability. If the value already exists, the calling token must have an ACL policy granting the "update" capability.

Examples

Writes the data to the key "creds":

$ vault kv put -mount=secret creds passcode=my-long-passcode

The data can also be consumed from a file on disk by prefixing with the "@" symbol. For example:

$ vault kv put -mount=secret foo @data.json

Or it can be read from stdin using the "-" symbol:

$ echo "abcd1234" | vault kv put -mount=secret foo bar=-

Usage

There are no flags beyond the standard set of flags included on all commands.

Output options

  • -field (string: "") - Print only the field with the given name. Specifying this option will take precedence over other formatting directives. The result will not have a trailing newline making it ideal for piping to other processes.

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

  • -cas (int: 0) - Specifies to use a Check-And-Set operation. If not set the write will be allowed. In order for a write to be successful, cas must be set to the current version of the secret. If set to 0 a write will only be allowed if the key doesn’t exist as unset keys do not have any version information. Also remember that soft deletes do not remove any underlying version data from storage. In order to write to a soft deleted key, the cas parameter must match the key's current version. The default is -1.

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

kv rollback

NOTE: This is a K/V Version 2 secrets engine command, and not available for Version 1.

The kv rollback command restores a given previous version to the current version at the given path. The value is written as a new version; for instance, if the current version is 5 and the rollback version is 2, the data from version 2 will become version 6. This command makes it easy to restore unintentionally overwritten data.

Examples

Restores the version 2 of the data at key "creds":

$ vault kv rollback -mount=secret -version=2 creds
Key              Value
---              -----
created_time     2019-06-06T17:07:19.299831Z
deletion_time    n/a
destroyed        false
version          6

Usage

There are no flags beyond the standard set of flags included on all commands.

Output options

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

  • -version (int: 0) - Specifies the version number that should be made current again.

kv undelete

NOTE: This is a K/V Version 2 secrets engine command, and not available for Version 1.

The kv undelete command undoes the deletes of the data for the provided version and path in the key-value store. This restores the data, allowing it to be returned on get requests.

Examples

Undelete version 3 of the key "creds":

$ vault kv undelete -mount=secret -versions=3 creds
Success! Data written to: secret/undelete/creds

Usage

There are no flags beyond the standard set of flags included on all commands.

Output options

  • -format (string: "table") - Print the output in the given format. Valid formats are "table", "json", or "yaml". This can also be specified via the VAULT_FORMAT environment variable.

Command options

  • -mount (string: "") - Specifies the path where the KV backend is mounted. If specified, the next argument will be interpreted as the secret path. If this flag is not specified, the next argument will be interpreted as the combined mount path and secret path, with /data/ automatically inserted for KV v2 secrets.

  • -versions ([]int: <required>) - Specifies the version number that should be made current again.

PreviouseventsNextlease

Last updated