consul/website/content/commands/kv/get.mdx

---
layout: commands
page_title: 'Commands: KV Get'
---

# Consul KV Get

Command: `consul kv get`

Corresponding HTTP API Endpoint: [\[GET\] /v1/kv/:key](/api-docs/kv#read-key)

The `kv get` command is used to retrieve the value from Consul's KV
store at the given key name. If no key exists with that name, an error is
returned. If a key exists with that name but has no data, nothing is returned.
A key name or prefix is required.

-> **Note**: When reading many entries under a given prefix, it may be worth
considering [`kv export`](/commands/kv/export) instead. The kv export output
can be used with [`kv import`](/commands/kv/import) to move entire trees between
Consul clusters. Alternatively, the [transaction API](/api-docs/txn) provides
support for performing up to 64 KV operations atomically.

The table below shows this command's [required ACLs](/api#authentication). Configuration of
[blocking queries](/api/features/blocking) and [agent caching](/api/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.

| ACL Required |
| ------------ |
| `key:read`   |

## Usage

Usage: `consul kv get [options] [KEY_OR_PREFIX]`

#### API Options

@include 'http_api_options_client.mdx'

@include 'http_api_options_server.mdx'

#### Enterprise Options

@include 'http_api_namespace_options.mdx'

@include 'http_api_partition_options.mdx'

#### KV Get Options

- `-base64` - Base 64 encode the value. The default value is false.

- `-detailed` - Provide additional metadata about the key in addition to the
  value such as the ModifyIndex and any flags that may have been set on the key.
  The default value is false.

- `-keys` - List keys which start with the given prefix, but not their values.
  This is especially useful if you only need the key names themselves. This
  option is commonly combined with the -separator option. The default value is
  false.

- `-recurse` - Recursively look at all keys prefixed with the given path. The
  default value is false.

- `-separator=<string>` - String to use as a separator for recursive lookups. The
  default value is "/", and only used when paired with the `-keys` flag. This will
  limit the prefix of keys returned, only up to the given separator.

## Examples

To retrieve the value for the key named "redis/config/connections" in the
KV store:

```shell-session hideClipboard
$ consul kv get redis/config/connections
5
```

This will return the original raw value stored in Consul.

If the key with the given name does not exist, an error is returned.

```shell-session hideClipboard
$ consul kv get not-a-real-key
Error! No key exists at: not-a-real-key
```

### Detailed Output

To view detailed information about the key, specify the `-detailed` flag.
This will output all known metadata about the key including `ModifyIndex`
and any user-supplied flags:

```shell-session hideClipboard
$ consul kv get -detailed redis/config/connections
CreateIndex      336
Flags            0
Key              redis/config/connections
LockIndex        0
ModifyIndex      336
Session          -
Value            5
```

### Recursively Reading By Prefix

To treat the path as a prefix and list all entries which start with the given
prefix, specify the `-recurse` flag:

```shell-session hideClipboard
$ consul kv get -recurse redis/
redis/config/connections:5
redis/config/cpu:128
redis/config/memory:512
```

Alternatively, combine with the `-detailed` flag to list detailed information
about all entries under a prefix:

```shell-session hideClipboard
$ consul kv get -recurse -detailed redis
CreateIndex      336
Flags            0
Key              redis/config/connections
LockIndex        0
ModifyIndex      336
Session          -
Value            5

CreateIndex      472
Flags            0
Key              redis/config/cpu
LockIndex        0
ModifyIndex      472
Session          -
Value            128

CreateIndex      471
Flags            0
Key              redis/config/memory
LockIndex        0
ModifyIndex      471
Session          -
Value            512
```

### Listing Keys

To just list the keys which start with the specified prefix, use the `-keys`
option instead. This is more performant and results in a smaller payload:

```shell-session hideClipboard
$ consul kv get -keys redis/config/
redis/config/connections
redis/config/cpu
redis/config/memory
```

By default, the `-keys` operation uses a separator of "/", meaning it will not
recurse beyond that separator. You can choose a different separator by setting
`-separator="<string>"`.

```shell-session hideClipboard
$ consul kv get -keys -separator="c" redis
redis/c
```

Alternatively, you can disable the separator altogether by setting it to the
empty string:

```shell-session hideClipboard
$ consul kv get -keys -separator="" redis
redis/config/connections
redis/config/cpu
redis/config/memory
```

To list all keys at the root, simply omit the prefix parameter:

```shell-session hideClipboard
$ consul kv get -keys
memcached/
redis/
```