vhsm kv
Learn to use kv command for interacting with vHSM's key/value secrets engine.
The kv
command groups subcommands for interacting with vHSM's key/value (K/V) secrets engine, supporting 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 where the secrets engine is mounted can be specified using the
-mount
flag. For example,vhsm kv get -mount=secret creds
.
Subcommands
Marks versions as deleted in K/V v2.
Permanently removes one or more versions in K/V v2.
Enables versioning for K/V v1.
Retrieves data from the K/V store.
Lists stored data or secrets.
Interacts with K/V metadata.
Updates data without overwriting existing data.
Creates or updates data in the K/V store.
Rolls back to a previous version.
Restores deleted versions.
Command Details
kv put
Stores or updates a key-value pair in K/V v2.
Example
vhsm kv put -mount=secret my-app/creds passcode=my-long-passcode
Output
====== Secret Path ======
secret/data/my-app/creds
======= Metadata =======
Key Value
--- -----
created_time 2025-03-04T13:45:29.982835Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 3
kv get
Retrieves data from the K/V secrets engine.
Example
vhsm kv get -mount=secret creds
-mount
Specifies the path where K/V is mounted.
-version
Specifies the version to retrieve (default: latest).
-field
Returns only the specified field's value.
Output
== Secret Path ==
secret/data/creds
======= Metadata =======
Key Value
--- -----
created_time 2025-03-04T13:39:56.810117Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 1
====== Data ======
Key Value
--- -----
passcode my-long-passcode
kv delete
Marks data as deleted (K/V v2 only).
Example
vhsm kv delete -mount=secret creds
-mount
Specifies the mount path.
-versions
Specifies versions to delete (K/V v2 only).
Output
Success! Data deleted (if it existed) at: secret/data/creds
kv destroy
Permanently removes specified versions (K/V v2 only).
Example
vhsm kv destroy -mount=secret -versions=11 creds
-mount
Specifies the mount path.
-versions
Specifies versions to permanently delete.
Output
Success! Data written to: secret/destroy/creds
kv enable-versioning
Enables versioning for a non-versioned K/V secrets engine (K/V v1).
Example
vhsm kv enable-versioning secret
Output
Success! Tuned the secrets engine at: secret/
kv list
Lists key names at the specified path.
Example
$ vhsm kv list -mount=secret my-app/
Output
Keys
----
creds
kv metadata
Interacts with metadata for versioned secrets.
kv metadata get
Retrieves metadata of a key.
Example
vhsm kv metadata get -mount=secret creds
-mount
Specifies the mount path.
Output
=== Metadata Path ===
secret/metadata/creds
========== Metadata ==========
Key Value
--- -----
cas_required false
created_time 2025-03-04T13:35:03.268548Z
current_version 1
custom_metadata <nil>
delete_version_after 0s
max_versions 5
oldest_version 0
updated_time 2025-03-04T13:39:56.810117Z
====== Version 1 ======
Key Value
--- -----
created_time 2025-03-04T13:39:56.810117Z
deletion_time 2025-03-04T13:41:56.71908Z
destroyed false
kv metadata delete
Deletes all versions and metadata for a key.
Example
vhsm kv metadata delete -mount=secret creds
kv metadata put
Creates or updates key settings in K/V v2.
Example
vhsm kv metadata put -mount=secret -max-versions=5 creds
-cas-required
Requires check-and-set for updates.
-max-versions
Limits the number of versions to retain.
-delete-version-after
Sets expiration time for key versions.
Output
Success! Data deleted (if it existed) at: secret/metadata/creds
kv patch
Updates data without overwriting existing values (K/V v2 only).
Example
vhsm kv patch -mount=secret my-app/creds ttl=48h
Output
====== Secret Path ======
secret/data/my-app/creds
======= Metadata =======
Key Value
--- -----
created_time 2025-03-04T13:48:58.266994Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 4
kv rollback
Restores a previous version of a key (K/V v2 only).
Example
vhsm kv rollback -mount=secret -version=4 my-app/creds
Output
Key Value
--- -----
created_time 2025-03-04T14:00:49.357078Z
custom_metadata <nil>
deletion_time n/a
destroyed false
version 5
kv undelete
Restores deleted versions of a key (K/V v2 only).
Example
vhsm kv undelete -mount=secret -versions=3 creds
Output
Success! Data written to: secret/undelete/creds
Last updated
Was this helpful?