consul-kv

Read a value from the key-value store

$ consul kv get [key]

$ consul kv put [key] [value]

$ consul kv delete [key]

consul kv [subcommand] [options]

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

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.

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.

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.

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.

consul(1)