# 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": ```shell-session $ 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 deletion_time n/a destroyed false version 1 ``` Read this value back: ```shell-session $ vault kv get -mount=secret creds == Secret Path == secret/data/creds ======= Metadata ======= Key Value --- ----- created_time 2022-06-15T20:14:17.107852Z custom_metadata deletion_time n/a destroyed false version 1 ====== Data ====== Key Value --- ----- passcode my-long-passcode ``` Get metadata for the key named "creds": ```shell-session $ 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 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": ```shell-session $ 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 deletion_time n/a destroyed false version 1 ====== Data ====== Key Value --- ----- passcode my-long-passcode ``` ### Usage ``` Usage: vault kv [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": ```shell-session $ 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": ```shell-session $ 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: )` - 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": ```shell-session $ 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: )` - 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". ```shell-session $ 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": ```shell-session $ vault kv get -mount=secret creds == Secret Path == secret/data/creds ======= Metadata ======= Key Value --- ----- created_time 2022-06-15T20:23:40.067093Z custom_metadata 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: ```shell-session $ vault kv get -mount=secret creds ====== Data ====== Key Value --- ----- passcode my-long-passcode ``` Return only the "creds" "passcode" key: ```shell-session $ 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": ```shell-session $ 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 [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": ```shell-session $ 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": ```shell-session $ 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": ```shell-session $ 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": ```shell-session $ 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": ```shell-session $ 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": ```shell-session $ 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": ```shell-session $ 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. ```shell-session $ 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: ```shell-session $ vault kv patch -mount=secret creds @data.json ``` Or it can be read from stdin using the "-" symbol: ```shell-session $ 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": ```shell-session $ 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: ```shell-session $ vault kv put -mount=secret foo @data.json ``` Or it can be read from stdin using the "-" symbol: ```shell-session $ 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": ```shell-session $ 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": ```shell-session $ 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: )` - Specifies the version number that should be made current again. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.enclaive.cloud/vault/cli/kv.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.