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

# Consul KV Get

Command: `consul kv get`

Corresponding HTTP API Endpoint: [\[GET\] /v1/kv/:key](https://www.consul.io/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.

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
$ consul kv get redis/config/connections
5
```

This will return the original, raw value stored in Consul. 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
$ consul kv get -detailed redis/config/connections
CreateIndex      336
Flags            0
Key              redis/config/connections
LockIndex        0
ModifyIndex      336
Session          -
Value            5
```

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

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

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

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

Or list detailed information about all pairs under a prefix:

```shell-session
$ 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
```

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
$ 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
$ 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
$ 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
$ consul kv get -keys
memcached/
redis/
```