Working with KV Secrets Engine

In this guide, you’ll learn how to manage secrets with Vault’s Key/Value (KV) Secrets Engine using the vault kv CLI. We’ll cover KV version 1 and version 2 operations:

• Core commands: put, get, delete, list
• KV V2–only versioning commands: undelete, destroy, patch, rollback

Master these commands to automate secrets management in scripts and CI/CD pipelines.

KV CLI Command Overview

Use vault kv <subcommand> to perform KV operations. The table below summarizes each subcommand:

Writing Data with vault kv put

Use vault kv put to store or update secrets. The syntax is:

vault kv put <mount-path>/<secret-path> key1=value1 key2=value2 ...

• <mount-path>/<secret-path>: The mount and path for your secret
• key=value: Each key/value pair becomes a field in the secret

KV Version 1 vs. Version 2

KV V1 Example

$ vault kv put kv/app/db pass=123
Success! Data written to: kv/app/db

KV V2 Example

$ vault kv put kv/app/db pass=123
Key            Value
---            -----
creation_time  2022-12-15T04:35:56.395821Z
deletion_time  n/a
destroyed      false
version        1

On KV V2, put returns extra metadata (creation time, deletion time, destroyed flag, and version).

Writing Multiple Pairs or JSON Files

Inline multiple pairs:

$ vault kv put kv/app/db pass=123 user=admin api=a8ee4b50cce124
Success! Data written to: kv/app/db

$ vault kv put kv/app/db @secrets.json

{"pass":"123","user":"admin","api":"a8ee4b50cce124"}

Reading Data with vault kv get

Retrieve secrets in table or JSON format.

Table Output

KV V1

$ vault kv get kv/app/db
====== Data ======
Key    Value
----   -----
pass   123
user   admin
api    a8ee4b50cce124

KV V2

$ vault kv get kv/app/db
===== Metadata =====
Key             Value
---             -----
creation_time   2022-12-15T04:35:56.395821Z
deletion_time   n/a
destroyed       false
version         1

===== Data =====
Key    Value
---    -----
pass   123
user   admin
api    a8ee4b50cce124

JSON Output for Automation

$ vault kv get -format=json kv/app/db

Pipe to jq for CI/CD automation:

vault kv get -format=json kv/app/db | jq '.data.data'

Reading Specific Versions (KV V2)

• Default (latest): vault kv get kv/app/db
• Specific: vault kv get -version=3 kv/app/db

If the latest version is soft‐deleted, only metadata is returned.

Updating Secrets

Overwrite with put

A full put replaces all fields:

$ vault kv put kv/app/db api=new-api-key
Key            Value
---            -----
version        2

Existing fields are lost; only the new api remains in version 2.

Revert Changes with rollback (KV V2)

$ vault kv rollback -version=1 kv/app/db
Key            Value
---            -----
version        3

This creates version 3 with data from version 1.

Merge Fields with patch (KV V2)

$ vault kv patch kv/app/db user=bryan
======= Metadata =======
Key            Value
---            -----
version        4

patch adds or updates fields without removing existing data.

Deleting Secrets

Soft Delete with delete

• KV V1: Permanently removes data
• KV V2: Marks the latest version as deleted (soft delete)

$ vault kv delete secret/app/database
Success! Data deleted (if it existed) at: secret/app/database

After Delete

KV V1:

$ vault kv get secret/app/database
No value found at secret/app/database

KV V2:

$ vault kv get secret/app/database
===== Metadata =====
Key            Value
---            -----
version        3
deletion_time  2022-12-15T17:42:03.369955Z
destroyed      false
# No Data table shown

Permanent Removal with destroy (KV V2)

$ vault kv destroy -versions=3 secret/app/web
Success! Data destroyed at: secret/app/web

Remove All Versions and Metadata

$ vault kv metadata delete secret/app/web
Success! All metadata and versions deleted at: secret/app/web

You’ve now mastered the KV Secrets Engine CLI operations for both KV V1 and KV V2. Next up: exploring the Transit Secrets Engine for encryption-as-a-service.

Links and References

• Vault KV Secrets Engine
• Vault CLI Documentation
• jq: Command-line JSON Processor