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> [<args>] [options]

-address=addr
    Consul agent address (default: 127.0.0.1:8501)

-http-addr=addr
    HTTP API address, overrides -address

-datacenter=name
    Target datacenter (default: auto-discovered)

-namespace=name
    Enterprise namespace to operate within

-token=token
    ACL token for authorization

-token-file=path
    File containing ACL token

-ca-file=path
    PEM CA cert for TLS

-insecure-skip-verify
    Skip TLS server certificate validation

-retry-max=N
    Max retries on failure (default: 2)

-recurse
    For get/list: recurse into subkeys

-format=fmt
    For get: output format (yaml,json,etc.)

-cas=index
    For put: check-and-set using modify index

-acquire=session
    For put: acquire lock via session

-release=session
    For put: release lock via session

-force
    Overwrite without confirmation

The consul kv command provides a command-line interface to interact with Consul's built-in key-value (KV) store, a highly available data store for dynamic configuration, feature flags, coordination, and leader election in distributed systems.

Consul KV supports hierarchical keys (using '/' delimiters) and stores opaque byte arrays up to 512KB per value. It offers multi-datacenter replication, watches for changes, and integrates with Consul's ACL system for secure access. Common use cases include storing service configuration that applications fetch at runtime, without needing external databases.

The command supports subcommands like get, put, delete, and list, with options for recursion, formatting, and conditional updates. It communicates via Consul's HTTP API, inheriting global flags for authentication, retries, and targeting specific agents or datacenters. In Consul Enterprise, namespaces enable multi-tenancy.

Key benefits include simplicity—no separate database needed—and tight integration with Consul's service discovery and health checking. Usage requires a running Consul cluster (server or agent with server proxying).

Requires a running Consul cluster; ACL policies may restrict access. KV values limited to 512KB. Not for high-throughput workloads—use dedicated stores like Redis if needed.
Subcommands have context-specific flags (e.g., -detailed for get).

get <KEY>: Retrieve value(s).
put <KEY> [<VALUE>]: Store value.
delete <KEYPREFIX>: Delete keys.
list <KEYPREFIX>: List keys.

consul kv put config/app foo=bar
consul kv get -recurse config/
consul kv delete foo -force

Introduced in Consul v0.5.1 (October 2014) by HashiCorp. Evolved with ACL support (v0.7, 2016), sessions/locks (v0.6), Enterprise namespaces (v1.4, 2018), and HTTP/2 optimizations in recent versions.

consul(1), curl(1), jq(1)