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

183 lines
4.9 KiB
Plaintext

---
layout: commands
page_title: 'Commands: KV Get'
---
# Consul KV Get
Command: `consul kv get`
Corresponding HTTP API Endpoint: [\[GET\] /v1/kv/:key](/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.
-> **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/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 hideClipboard
$ consul kv get redis/config/connections
5
```
This will return the original raw value stored in Consul.
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
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
$ 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
To treat the path as a prefix and list all entries which start with the given
prefix, specify the `-recurse` flag:
```shell-session hideClipboard
$ 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:
```shell-session hideClipboard
$ 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`
option instead. This is more performant and results in a smaller payload:
```shell-session hideClipboard
$ 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
redis/c
```
Alternatively, you can disable the separator altogether by setting it to the
empty string:
```shell-session hideClipboard
$ 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
$ consul kv get -keys
memcached/
redis/
```