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

183 lines
4.9 KiB
Plaintext
Raw Normal View History

2016-09-26 15:12:14 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: KV Get'
2016-09-26 15:12:14 +00:00
---
# Consul KV Get
Command: `consul kv get`
2022-01-11 13:26:58 +00:00
Corresponding HTTP API Endpoint: [\[GET\] /v1/kv/:key](/api-docs/kv#read-key)
2017-04-04 16:33:22 +00:00
The `kv get` command is used to retrieve the value from Consul's KV
2016-09-26 15:12:14 +00:00
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.
2018-06-21 18:21:26 +00:00
A key name or prefix is required.
2016-09-26 15:12:14 +00:00
-> **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-docs/features/blocking) and [agent caching](/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.
| ACL Required |
| ------------ |
| `key:read` |
2016-09-26 15:12:14 +00:00
## Usage
Usage: `consul kv get [options] [KEY_OR_PREFIX]`
#### API Options
2020-04-07 18:55:19 +00:00
@include 'http_api_options_client.mdx'
2020-04-07 23:56:08 +00:00
2020-04-07 18:55:19 +00:00
@include 'http_api_options_server.mdx'
2016-09-26 15:12:14 +00:00
#### Enterprise Options
2020-04-07 18:55:19 +00:00
@include 'http_api_namespace_options.mdx'
@include 'http_api_partition_options.mdx'
2016-09-26 15:12:14 +00:00
#### KV Get Options
2020-04-07 18:55:19 +00:00
- `-base64` - Base 64 encode the value. The default value is false.
2020-04-07 18:55:19 +00:00
- `-detailed` - Provide additional metadata about the key in addition to the
2016-09-26 15:12:14 +00:00
value such as the ModifyIndex and any flags that may have been set on the key.
The default value is false.
2020-04-07 18:55:19 +00:00
- `-keys` - List keys which start with the given prefix, but not their values.
2016-09-26 15:12:14 +00:00
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.
2020-04-07 18:55:19 +00:00
- `-recurse` - Recursively look at all keys prefixed with the given path. The
2016-09-26 15:12:14 +00:00
default value is false.
2020-04-07 18:55:19 +00:00
- `-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
2018-12-07 19:57:00 +00:00
limit the prefix of keys returned, only up to the given separator.
2016-09-26 15:12:14 +00:00
## Examples
To retrieve the value for the key named "redis/config/connections" in the
2017-04-04 16:33:22 +00:00
KV store:
2016-09-26 15:12:14 +00:00
```shell-session hideClipboard
2016-09-26 15:12:14 +00:00
$ consul kv get redis/config/connections
5
```
This will return the original raw value stored in Consul.
2016-09-26 15:12:14 +00:00
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
2016-09-26 15:12:14 +00:00
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
2016-09-26 15:12:14 +00:00
$ 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
2016-09-26 15:12:14 +00:00
To treat the path as a prefix and list all entries which start with the given
prefix, specify the `-recurse` flag:
2016-09-26 15:12:14 +00:00
```shell-session hideClipboard
2016-09-26 15:12:14 +00:00
$ 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:
2016-09-26 15:12:14 +00:00
```shell-session hideClipboard
2016-09-26 15:12:14 +00:00
$ 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`
2016-09-26 15:12:14 +00:00
option instead. This is more performant and results in a smaller payload:
```shell-session hideClipboard
2016-09-26 15:12:14 +00:00
$ 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
2016-09-26 15:12:14 +00:00
redis/c
```
Alternatively, you can disable the separator altogether by setting it to the
empty string:
```shell-session hideClipboard
2016-09-26 15:12:14 +00:00
$ 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
2016-09-26 15:12:14 +00:00
$ consul kv get -keys
memcached/
redis/
```