vault kv put: Usage, Options & Common CI Errors

Write or overwrite a secret in Vault’s key/value engine.

vault kv put writes a secret to the KV engine, creating a new version (KV v2). In CI you typically feed values from stdin or a file rather than the command line to keep them out of process listings and logs.

What it does

vault kv put <path> key=value writes the given keys to the KV path, replacing all existing keys at that path (KV v2 keeps prior versions). To merge rather than replace, use vault kv patch. Reading a value from stdin with key=- avoids exposing it in shell history or the process table.

Common usage

# Write a secret (replaces all keys at the path)
vault kv put secret/myapp/db username=app password=s3cr3t

# Read a value from stdin (key=-) to avoid leaking it
cat token.txt | vault kv put secret/myapp/api token=-

# Merge a single key without replacing others
vault kv patch secret/myapp/db rotated_at=2026-06-25

Common error in CI: permission denied / check-and-set required

put fails with "permission denied" (policy lacks create/update on the path) or "check-and-set parameter required for this call" when the mount enforces CAS. Fix: grant the token create+update on <mount>/data/<path> and, when CAS is enabled, pass -cas=<current_version> (use -cas=0 to create only if absent). Prefer kv patch to update one key so you do not accidentally drop the others that kv put replaces.

Key options

Related guides