kv
The kv command groups subcommands for interacting with Vault's key/value
secrets engine (both KV version 1 and KV
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.
The deprecated path-like syntax can also be used (e.g. vault kv get secret/creds), but this should be avoided
for KV v2, because it is not actually the full API path to the secret
(secret/data/foo) and may cause confusion.
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.
Mount flag syntax (KV)
All kv commands can alternatively refer to the path to the KV secrets engine using a flag-based syntax like $ vault kv get -mount=secret password
instead of $ vault kv get secret/password. The mount flag syntax was created to mitigate confusion caused by the fact that for KV v2 secrets,
their full path (used in policies and raw API calls) actually contains a nested /data/ element (e.g. secret/data/password) which can be easily overlooked when using
the above KV v1-like syntax secret/password. To avoid this confusion, all KV-specific docs pages will use the -mount flag.
Exit codes
The Vault CLI aims to be consistent and well-behaved unless documented otherwise.
Local errors such as incorrect flags, failed validations, or wrong numbers of arguments return an exit code of 1.
Any remote errors such as API failures, bad TLS, or incorrect API parameters return an exit status of 2
Some commands override this default where it makes sense. These commands document this anomaly.
Examples
Create or update the key named "creds" in the KV 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.107852Zcustom_metadata <nil>deletion_time n/adestroyed falseversion 1Read this value back:
$ vault kv get -mount=secret creds== Secret Path ==secret/data/creds ======= Metadata =======Key Value--- -----created_time 2022-06-15T20:14:17.107852Zcustom_metadata <nil>deletion_time n/adestroyed falseversion 1 ====== Data ======Key Value--- -----passcode my-long-passcodeGet metadata for the key named "creds":
$ vault kv metadata get -mount=secret creds=== Metadata Path ===secret/metadata/creds ========== Metadata ==========Key Value--- -----cas_required falsecreated_time 2022-06-15T20:14:17.107852Zcurrent_version 1custom_metadata <nil>delete_version_after 0smax_versions 0oldest_version 0updated_time 2022-06-15T20:14:17.107852Z ====== Version 1 ======Key Value--- -----created_time 2022-06-15T20:14:17.107852Zdeletion_time n/adestroyed falseGet 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.107852Zcustom_metadata <nil>deletion_time n/adestroyed falseversion 1 ====== Data ======Key Value--- -----passcode my-long-passcodeUsage
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 storeFor more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar.