---
layout: docs
page_title: kv metadata - Command
description: |-
  The "kv metadata" command has subcommands for interacting with the metadata
  endpoint in Vault's key-value store.
---

# kv metadata

~> **NOTE:** This is a [K/V Version 2](/docs/secrets/kv/kv-v2) secrets
engine command, and not available for Version 1.

The `kv metadata` command has subcommands for interacting with the metadata and
versions for the versioned secrets (K/V Version 2 secrets engine) at the
specified path.

## Usage

```text
Usage: vault kv metadata <subcommand> [options] [args]

  # ...

Subcommands:
    delete    Deletes all versions and metadata for a key in the KV store
    get       Retrieves key metadata from the KV store
    put       Sets or updates key settings in the KV store
```

### kv metadata delete

The `kv metadata delete` command deletes all versions and metadata for the
provided key.

#### Examples

Deletes all versions and metadata of the key "creds":

```shell-session
$ vault kv metadata delete -mount=secret creds
Success! Data deleted (if it existed) at: secret/metadata/creds
```

### kv metadata get

The `kv metadata get` command retrieves the metadata of the versioned secrets at
the given key name. If no key exists with that name, an error is returned.

#### Examples

Retrieves the metadata of the key name, "creds":

```shell-session
$ vault kv metadata get -mount=secret creds
=== Metadata Path ===
secret/metadata/creds

========== Metadata ==========
Key                     Value
---                     -----
cas_required            false
created_time            2019-06-28T15:53:30.395814Z
current_version         5
delete_version_after    0s
max_versions            0
oldest_version          0
updated_time            2019-06-28T16:01:47.40064Z

====== Version 1 ======
Key              Value
---              -----
created_time     2019-06-28T15:53:30.395814Z
deletion_time    n/a
destroyed        false

====== Version 2 ======
Key              Value
---              -----
created_time     2019-06-28T16:01:36.676912Z
deletion_time    n/a
destroyed        false

...
```

### kv metadata put

The `kv metadata put` command can be used to create a blank key in the K/V v2
secrets engine or to update key configuration for a specified key.

#### Examples

Create a key in the K/V v2 with no data at the key "creds":

```shell-session
$ vault kv metadata put -mount=secret creds
Success! Data written to: secret/metadata/creds
```

Set the maximum number of versions to keep for the key "creds":

```shell-session
$ vault kv metadata put -mount=secret -max-versions=5 creds
Success! Data written to: secret/metadata/creds
```

**NOTE:** If not set, the backend’s configured max version is used. Once a key
has more than the configured allowed versions the oldest version will be
permanently deleted.

Require Check-and-Set for the key "creds":

```shell-session
$ vault kv metadata put -mount=secret -cas-required creds
```

**NOTE:** When check-and-set is required, the key will require the `cas`
parameter to be set on all write requests. Otherwise, the backend’s
configuration will be used.

Set the length of time before a version is deleted for the key "creds":

```shell-session
$ vault kv metadata put -mount=secret -delete-version-after="3h25m19s" creds
```

**NOTE:** If not set, the backend's configured Delete-Version-After is used. If
set to a duration greater than the backend's, the backend's Delete-Version-After
setting will be used. Any changes to the Delete-Version-After setting will only
be applied to new versions.

#### Output Options

- `-format` `(string: "table")` - Print the output in the given format. Valid
  formats are "table", "json", or "yaml". This can also be specified via the
  `VAULT_FORMAT` environment variable.

#### Subcommand Options

- `-cas-required` `(bool: false)` - If true the key will require the cas
  parameter to be set on all write requests. If false, the backend’s
  configuration will be used. The default is false.

- `-max-versions` `(int: 0)` - The number of versions to keep per key. If not
  set, the backend’s configured max version is used. Once a key has more than the
  configured allowed versions the oldest version will be permanently deleted.

- `-delete-version-after` `(string:"0s")` – Set the `delete-version-after` value
  to a duration to specify the `deletion_time` for all new versions written to
  this key. If not set, the backend's `delete_version_after` will be used. If
  the value is greater than the backend's `delete_version_after`, the backend's
  `delete_version_after` will be used. Accepts [duration format strings](/docs/concepts/duration-format).

- `-custom-metadata` `(string: "")` - Specifies a key-value pair for the
  `custom_metadata` field. This can be specified multiple times to add multiple
  pieces of metadata.

- `-mount` `(string: "")` - Specifies the path where the KV backend is mounted. 
  If specified, the next argument will be interpreted as the secret path. If 
  this flag is not specified, the next argument will be interpreted as the 
  combined mount path and secret path, with /data/ automatically inserted for 
  KV v2 secrets.