---
layout: "docs"
page_title: "Commands: KV Get"
sidebar_current: "docs-commands-kv-get"
---

# Consul KV Get

Command: `consul kv get`

The `kv get` command is used to retrieves the value from Consul's key-value
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.
If the name or prefix is omitted, it defaults to "" which is the root of the
key-value store.

## Usage

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

#### API Options

<%= partial "docs/commands/http_api_options" %>

#### KV Get Options

* `-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 between keys. The default
  value is "/", but this option is only taken into account when paired with the
  -keys flag.

## Examples

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

```
$ 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:

```
$ 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:

```
$ 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:

```
$ 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:

```
$ 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:

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

```
$ consul kv get -keys -separator="s" redis
redis/c
```

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

```
$ 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:

```
$ consul kv get -keys
memcached/
redis/
```