Use when working with Consul — services, KV store, health checks, service mesh, or any Consul-related task
Read state.json for active_company, then load config.yaml for that company. Consul configuration lives under cloud.consul and provides:
| Field | Purpose |
|---|---|
addr | Consul API address (e.g. https://consul.example.com:8500) |
token_ref | Reference to the ACL token in the secrets store |
CONSUL_HTTP_ADDR and CONSUL_HTTP_TOKEN are set automatically when you run hat on <company>. You do not need to set these manually.
# List all cluster members (servers and clients)
consul members
# Show detailed member info including roles
consul members -detailed
# Check Raft cluster health and leader status
consul operator raft list-peers
# Stream live agent logs (useful for debugging)
consul monitor
# Stream live logs at a specific level
consul monitor -log-level=debug
# Check agent health and configuration
consul info
# List all registered services
consul catalog services
# List all registered nodes
consul catalog nodes
# List nodes providing a specific service
consul catalog nodes -service=<service-name>
# Check health status of all services
consul health checks --service <service-name>
# List passing/warning/critical health checks
consul health checks --state passing
consul health checks --state warning
consul health checks --state critical
# List service mesh intentions
consul intention list
# Read a specific intention
consul intention check <source> <destination>
# Read a single key from the KV store
consul kv get <key>
# Read a key and show metadata (flags, modify index)
consul kv get -detailed <key>
# List all keys under a prefix (recursive)
consul kv get -recurse <prefix>/
# Write a key (ONLY when explicitly instructed)
consul kv put <key> <value>
# Write a key from a file (ONLY when explicitly instructed)
consul kv put <key> @<file>
# Delete a single key (ONLY when explicitly instructed)
consul kv delete <key>
# Delete all keys under a prefix (ONLY when explicitly instructed)
consul kv delete -recurse <prefix>/
Consul exposes a DNS interface on port 8600 (by default on localhost) for service discovery queries.
# Resolve a service address via Consul DNS
dig @127.0.0.1 -p 8600 <service-name>.service.consul
# Resolve with SRV records (includes port information)
dig @127.0.0.1 -p 8600 <service-name>.service.consul SRV
# Resolve a service in a specific datacenter
dig @127.0.0.1 -p 8600 <service-name>.service.<datacenter>.consul
# Resolve a node address
dig @127.0.0.1 -p 8600 <node-name>.node.consul
# Resolve a tagged service variant
dig @127.0.0.1 -p 8600 <tag>.<service-name>.service.consul
# Check if the Consul DNS port is reachable
dig @127.0.0.1 -p 8600 consul.service.consul
When you need to understand what services are registered and their health status:
List all registered services:
consul catalog services
For each service of interest, list nodes providing it:
consul catalog nodes -service=<service-name>
Check health checks for the service:
consul health checks --service <service-name>
Look for checks in critical state and note the Output field for error details.
Verify the service is resolvable via DNS:
dig @127.0.0.1 -p 8600 <service-name>.service.consul
When you need to inspect configuration stored in Consul's KV store:
List all keys under a known prefix:
consul kv get -recurse <prefix>/
Read a specific key with full metadata:
consul kv get -detailed <key>
The ModifyIndex in the metadata helps you determine when the key was last changed.
For multi-line or binary values, pipe through base64 -D or inspect carefully.
When investigating cluster issues or before maintenance:
Check all cluster members and their status:
consul members
Look for members in failed or left state.
Verify Raft leader election and peer count:
consul operator raft list-peers
Confirm there is exactly one Leader and all expected servers are listed.
Check agent-level metrics and configuration:
consul info
If issues are found, tail live agent logs to see what is happening:
consul monitor -log-level=info
When a service cannot be resolved via DNS:
Confirm the service is registered:
consul catalog services
Check the health of the service:
consul health checks --service <service-name>
Only passing instances are returned in DNS queries by default.
Attempt a DNS resolution:
dig @127.0.0.1 -p 8600 <service-name>.service.consul
If no answer is returned, check if all instances are unhealthy (critical checks exclude them from DNS).
Try resolving with all health states (using the any tag):
dig @127.0.0.1 -p 8600 <service-name>.service.consul
If the service exists but all checks are critical, this confirms the health issue.
Review health check output for details:
consul health checks --service <service-name> --state critical
Never run the following without an explicit instruction from the user:
consul kv put — writes or overwrites a KV entryconsul kv delete — deletes a KV key or treeconsul leave — gracefully removes the agent from the clusterconsul force-leave — forcibly removes a node from the clusterRead-only commands (consul members, consul catalog services, consul catalog nodes, consul health checks, consul kv get, consul kv get -recurse, consul intention list, consul operator raft list-peers, consul monitor, consul info) are always safe to run.