consul-kv
Manage Consul key-value store data
TLDR
Read a value from the key-value store
Store a new key-value pair
Delete a key-value pair
SYNOPSIS
consul kv [subcommand] [options]
PARAMETERS
get
Retrieves the value associated with the specified key. Defaults to the value on stdout.
get -detailed
Retrieves the value associated with the specified key with verbose output.
get -decode
Attempt to decode the value with base64.
get -recurse
Lists all keys and values under the specified prefix recursively. Useful for retrieving entire configuration trees.
put
Sets the value for the specified key. Overwrites existing values.
delete
Deletes the specified key. Note that this command is destructive.
delete -recurse
Deletes all keys under the specified prefix recursively. Use with extreme caution!
export
Exports the key-value store as a serialized stream. Useful for backups or migrations.
import
Imports a serialized stream into the key-value store. Useful for restoring backups.
-datacenter
Specifies the datacenter to query. If not provided, the default datacenter configured in Consul is used.
-http-addr
Address of the Consul agent to query
DESCRIPTION
The `consul kv` command provides a command-line interface for interacting with Consul's key-value store. It allows users to read, write, delete, and list keys and their corresponding values within the Consul cluster's data store. This is a fundamental tool for managing configuration data, service discovery information, and other application-related data within a Consul-based infrastructure. The command facilitates the dynamic configuration of applications and services, allowing for changes to be pushed to the cluster without requiring restarts or redeployments. It supports various data types (strings, integers, booleans) and allows for complex data structures to be serialized as strings (e.g., JSON). The command is an integral part of Consul's ecosystem, enabling programmatic access to the key-value store for automation and integration with other tools and systems. Its use extends from simple configuration management to more advanced scenarios like feature flagging, dynamic routing, and distributed locking.
CAVEATS
Changes to the Consul KV store are immediately reflected, meaning applications must be designed to handle configuration updates gracefully. Using `-recurse` with `delete` can have severe consequences if the wrong prefix is specified. Always double-check your prefixes before running destructive operations.
ERROR HANDLING
The `consul kv` command will return a non-zero exit code if an error occurs, such as a connection problem with the Consul agent or an invalid key. Always check the exit code in scripts and automation workflows.
ACLS (ACCESS CONTROL LISTS)
Access to the key-value store is governed by Consul's ACL system. Ensure the Consul agent has the necessary permissions to read, write, or delete keys based on the ACL policies in place. Insufficient permissions will result in errors when attempting to perform operations.
SEE ALSO
consul(1)