KV

Consul /kv endpoint

Subcommand	Synopsis
bulkload	Bulkload value to the K/V store
delete	Delete a given path from the K/V
keys	List K/V keys
lock	Acquire a lock on a given path
read	Read a value from a given path
unlock	Release a lock on a given path
watch	Watch for changes to a K/V path
write	Write a value to a given path

bulkload

API Reference

Bulkload value to the K/V store

Basic Usage

Usage: consul-cli kv bulkload [options]

Command Line Options

• --json=<file>
  Path to a JSON file to import

• --prefix=<prefix>
  When specified, prefix all keys with this path

Examples

$ echo '{"foo":"bar"}' > import.json
$ ./consul-cli kv bulkload --json=import.json
$ ./consul-cli kv read "" --recurse=true --format=json | jq from_entries
{
  "foo": "bar"
}
$ ./consul-cli kv bulkload --json=import.json --prefix=test
$ ./consul-cli kv read "" --recurse=true --format=json | jq from_entries
{
  "foo": "bar",
  "test/foo": "bar"
}

---

delete

API Reference

Delete a given path from the K/V store

Basic Usage

Usage: consul-cli kv delete [options] path

Command Line Options

• --modifyindex=<index>
  Perform a Check-and-Set delete on the path. If the index is non zero, the node is only deleted if <index> matches the node's ModifyIndex

• --recurse
  When specified, all nodes that are prefixed with path are deleted

Examples

$ ./consul-cli kv delete --recurse test
$ ./consul-cli kv read test/key1
$

---

keys

API Reference

List K/V keys

Basic Usage

Usage: consul-cli vk keys [options] path

Command Line Options

• --separator=<path_separator> Only list keys up to a given separator.

Examples

$ ./consul-cli kv keys /
vault/core/audit
vault/core/auth
vault/core/keyring
vault/core/lock
vault/core/master
vault/core/mounts
vault/core/seal-config
vault/sys/policy/default
vault/sys/token/salt
$ ./consul-cli kv keys /vault/ --separator=/
vault/core/
vault/sys/

---

lock

API Reference

Acquire a lock on the given path

Basic Usage

Usage: consul-cli kv lock [options] path

Command Line Options

• --behavior=[release|delete]
  Node behavior when the owning session is invalidated. With the default behavior of release, the lock is released when the session expires. With delete, the node is deleted from the K/V store

• --ttl=<duration>
  Time to live for the lock. When the lock expires, the session is invalidated and the lock is either released or the node is deleted according to the behavior. A duration of zero indicates that the lock never expires

• --lock-delay=<duration>
  The amount of time before another process can acquire the lock after it is released. A duration of zero indicates that the lock can be immediately acquired after release. The default is 15s

• --session=<sessionId>
  Use the sessionId instead of creating a new one.

Examples

$ ./consul-cli kv lock --ttl=0 test/locks
ba7c8cda-d197-a062-4e3e-f9a737237aa1
$ ./consul-cli kv read --format=prettyjson test/locks
{
  "Key": "test/locks",
  "CreateIndex": 386,
  "ModifyIndex": 386,
  "LockIndex": 1,
  "Flags": 0,
  "Value": "",
  "Session": "ba7c8cda-d197-a062-4e3e-f9a737237aa1"
}

---

read

API Reference

Retrieve the given path from the K/V store

Basic Usage

Usage: consul-cli kv read [options] path

Command Line Options

• --fields=<field1,field2,...>
  A comma separated list of fields to display when format is text. The default field list is Value

• --format=[text|json|prettyjson]
  Specify the output format. One of text, json or prettyjson

• --delimiter=<fs>
  String delimiter to separate the fields when the format is text. The default is space ' '

• --header
  When specified, output a header row when the format is text. The default is false

• --recurse
  Read all of the nodes

Examples

$ ./consul-cli kv read test/node/key1 
Value1
$ ./consul-cli kv read --format=prettyjson test/node/key2 
{
  "Key": "test/node/key2",
  "CreateIndex": 317,
  "ModifyIndex": 317,
  "LockIndex": 0,
  "Flags": 0,
  "Value": "Value2",
  "Session": ""
}
$ ./consul-cli kv read --recurse --fields=key,value --header \
    --format=text --delimiter=: test/node
#key:value
test/node/deep/key3:Value3
test/node/key1:Value1
test/node/key2:Value2

---

unlock

API Reference

Release the lock on a given path

Basic Usage

Usage: consul-cli kv unlock [options] path

Command Line Options

• --session (* Required)
  The session ID of the lock holder. This is returned from the consul-cli kv lock command.

• --no-destroy
  When set, the session is not destroyed. By default the session is destroyed when the lock is released

Examples

$ ./consul-cli kv unlock --session=ba7c8cda-d197-a062-4e3e-f9a737237aa1 test/locks

---

watch

API Reference

Watch a node for changes. This implements the ?index HTTP option as a separate consul-cli command. The command line arguments and output is the same as the kv read command with the addition of the --wait-index option.

Basic Usage

Usage: consul-cli kv watch [options] path

Command Line Options

• --fields=<field1,field2,...>
  A comma separated list of fields to display when format is text. The default field list is Value

• --format=[text|json|prettyjson]
  Specify the output format. One of text, json or prettyjson

• --delimiter=<fs>
  String delimiter to separate the fields when the format is text. The default is space ' '

• --header
  When specified, output a header row when the format is text. The default is false

• --recurse
  Read all of the nodes

• --wait-index=<modifyIndex>
  Use the value of this option as the WaitIndex. If the node's ModifyIndex is greater than modifyIndex, the node is returned. The default value of 0 will immediately return the node if it already exists.

Examples

$ ./consul-cli kv watch test/node/key1 
Value1

---

write

API Reference

Write a value to the given path. The value can be either text or the path to a file via @/path/to/file.

Basic Usage

Usage: consul-cli kv write [options] path value

Command Line Options

• --modifyindex=<index>
  Perform a Check-and-Set write on the node. The write only occurs if the ModifyIndex of the node matches <index>

• --flags=<number>
  Set the Flags field of the node to a integer value between 0 and (2^64 - 1)

Examples

$ ./consul-cli kv write test/key1 Value1
$ ./consul-cli kv write test/etc/hosts @/etc/hosts