> 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 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.enclaive.cloud/virtual-hsm/cli/storage-and-data-mangement/vhsm-kv.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.