open-consul/website/pages/docs/commands/kv/get.mdx

158 lines
3.9 KiB
Plaintext

---
layout: docs
page_title: 'Commands: KV Get'
sidebar_title: get
---
# Consul KV Get
Command: `consul kv get`
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.
## 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'
#### 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/
```