mirror of https://github.com/hashicorp/consul
158 lines
3.9 KiB
Markdown
158 lines
3.9 KiB
Markdown
---
|
|
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/
|
|
```
|