183 lines
4.9 KiB
Plaintext
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-docs#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` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul kv get [options] [KEY_OR_PREFIX]`
|
|
|
|
#### Command 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.
|
|
|
|
#### Enterprise Options
|
|
|
|
@include 'http_api_partition_options.mdx'
|
|
|
|
@include 'http_api_namespace_options.mdx'
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
@include 'http_api_options_server.mdx'
|
|
|
|
## 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/
|
|
```
|