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:

Subcommand	Description
put	Write or update secrets
get	Read secrets
delete	Remove latest version (soft delete in V2)
list	List child keys
undelete	Restore deleted version (KV V2 only)
destroy	Permanently delete specific versions
patch	Merge fields into an existing version
rollback	Revert to a previous version (KV V2)

The image is a guide on using the vault kv command in the CLI, detailing various operations like put, get, delete, and list, with additional commands available for KV V2.

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

You can also read key/value pairs from a JSON file:

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

secrets.json example:

{"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)

destroy permanently deletes specified versions. This action cannot be undone.

$ 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.

Introduction

Introduction to Vault

Learning the Vault Architecture

Installing Vault

Compare Authentication Methods

Create Vault Policies

Assess Vault Tokens

Compare and Configure Secrets Engines

Vault Agent

Vault Replication

Working with KV Secrets Engine

KV CLI Command Overview

Writing Data with `vault kv put`

KV Version 1 vs. Version 2

KV V1 Example

KV V2 Example

Writing Multiple Pairs or JSON Files

Reading Data with `vault kv get`

Table Output

KV V1

KV V2

JSON Output for Automation

Reading Specific Versions (KV V2)

Updating Secrets

Overwrite with `put`

Revert Changes with `rollback` (KV V2)

Merge Fields with `patch` (KV V2)

Deleting Secrets

Soft Delete with `delete`

After Delete

Permanent Removal with `destroy` (KV V2)

Remove All Versions and Metadata

Links and References

Watch Video

​KV CLI Command Overview

​Writing Data with vault kv put

​KV Version 1 vs. Version 2

​KV V1 Example

​KV V2 Example

​Writing Multiple Pairs or JSON Files

​Reading Data with vault kv get

​Table Output

​KV V1

​KV V2

​JSON Output for Automation

​Reading Specific Versions (KV V2)

​Updating Secrets

​Overwrite with put

​Revert Changes with rollback (KV V2)

​Merge Fields with patch (KV V2)

​Deleting Secrets

​Soft Delete with delete

​After Delete

​Permanent Removal with destroy (KV V2)

​Remove All Versions and Metadata

​Links and References

Watch Video

KV CLI Command Overview

Writing Data with `vault kv put`

KV Version 1 vs. Version 2

KV V1 Example

KV V2 Example

Writing Multiple Pairs or JSON Files

Reading Data with `vault kv get`

Table Output

KV V1

KV V2

JSON Output for Automation

Reading Specific Versions (KV V2)

Updating Secrets

Overwrite with `put`

Revert Changes with `rollback` (KV V2)

Merge Fields with `patch` (KV V2)

Deleting Secrets

Soft Delete with `delete`

After Delete

Permanent Removal with `destroy` (KV V2)

Remove All Versions and Metadata

Links and References