> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/virtual-hsm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/virtual-hsm/cli/storage-and-data-mangement/vhsm-kv.md). # vhsm kv 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 | Command | Description | | -------------------------------------------- | --------------------------------------------------- | | [`delete`](#kv-delete) | Marks versions as deleted in K/V v2. | | [`destroy`](#kv-destroy) | Permanently removes one or more versions in K/V v2. | | [`enable-versioning`](#kv-enable-versioning) | Enables versioning for K/V v1. | | [`get`](#kv-get) | Retrieves data from the K/V store. | | [`list`](#kv-list) | Lists stored data or secrets. | | [`metadata`](#kv-metadata) | Interacts with K/V metadata. | | [`patch`](#kv-patch) | Updates data without overwriting existing data. | | [`put`](#kv-put) | Creates or updates data in the K/V store. | | [`rollback`](#kv-rollback) | Rolls back to a previous version. | | [`undelete`](#kv-undelete) | 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 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 ``` | Option | Description | | ---------- | ---------------------------------------------------- | | `-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 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 ``` | Option | Description | | ----------- | ------------------------------------------- | | `-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 ``` | Option | Description | | ----------- | ----------------------------------------- | | `-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 ``` | Option | Description | | -------- | ------------------------- | | `-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 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 ``` | Option | Description | | ----------------------- | ---------------------------------------- | | `-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 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 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 ```