consul

Display help

$ consul --help

$ consul [subcommand] --help

$ consul --version

consul subcommand [options]

agent
    Runs a Consul agent. This is the core process that either serves as a cluster server or a client forwarding requests.

kv
    Interacts with Consul's distributed Key-Value (KV) store, allowing data to be put, retrieved, and deleted.

catalog
    Allows interaction with the service catalog, such as listing registered services or nodes.

services
    Lists the services registered against the local agent.

acl
    Manages Access Control Lists (ACLs) to secure communication and access within Consul.

operator
    Provides commands for cluster-level operations, such as managing Raft peers or autopilot configurations.

join
    Instructs a Consul agent to join an existing cluster by connecting to one or more known agents.

leave
    Gracefully causes a Consul agent to leave the cluster. Useful for planned maintenance or shutdowns.

members
    Lists the members (agents) currently known to the Consul cluster.

reload
    Triggers a graceful reload of the agent's configuration without restarting the process.

status
    Reports the status of the Consul cluster, including server leader and Raft peer information.

validate
    Validates configuration files and policies for syntax and semantic correctness.

version
    Prints the Consul version and build information.

[flags]
    Most subcommands accept specific flags to modify behavior. Common flags include:
-dev (for agent): Runs a single-node development agent.
-server (for agent): Specifies the agent should run in server mode.
-bootstrap-expect (for agent): Sets the number of expected server nodes for initial cluster bootstrap.
-data-dir (for agent): Specifies the directory for agent state.
-config-dir (for agent): Specifies a directory to load configuration files from.
-h or --help: Displays help for the specific subcommand.

The consul command is the primary command-line interface (CLI) for HashiCorp Consul, a distributed service mesh that provides service discovery, configuration, and segmentation functionality. It serves two main purposes:

1. Running the Consul Agent: When used with the agent subcommand, it starts and operates a Consul agent process, which can run as either a server (participating in raft consensus, storing cluster state) or a client (forwarding requests to servers, running health checks).
2. Interacting with the Consul Cluster: The CLI allows users and automated scripts to interact with a running Consul cluster. This includes registering services, querying the service catalog, managing the Key-Value (KV) store, configuring Access Control Lists (ACLs), checking health statuses, and performing cluster operations.

Consul is widely used in modern cloud and datacenter environments to manage dynamic infrastructure, enabling applications to discover and communicate with each other reliably and securely, even as their network locations change.

The consul command is not a standard Linux utility but part of the HashiCorp Consul application. Its effective use requires an understanding of distributed systems, networking, and the Consul architecture. Running a production Consul cluster involves careful planning for high availability, disaster recovery, and security, often leveraging external tools like cloud provider services or configuration management. Misconfiguration can lead to cluster instability or data loss. It typically runs as a long-lived service, often managed by init systems like Systemd.

A Consul agent can run in two modes:

Server: Participates in the Raft consensus algorithm, stores the cluster's state (service catalog, KV data, ACLs), and acts as the backbone of the cluster. A Consul cluster requires at least one server, and typically 3 or 5 for high availability.
Client: Forwards all RPC requests to a server. Clients run health checks, register services, and handle DNS queries locally, but they do not store persistent cluster state. Most application nodes run as Consul clients.

Consul agents are typically configured via configuration files (JSON or HCL format) specified with the -config-dir or -config-file flags when starting the agent. These files define network bindings, data directories, security settings, and integration points.

Consul includes an optional built-in web user interface accessible via a browser. This UI provides a visual representation of the service catalog, nodes, KV store, and ACLs, and can be enabled by passing the -ui flag to the agent subcommand.

HashiCorp Consul was initially released in 2014 by HashiCorp, known for other infrastructure tools like Vagrant, Terraform, and Vault. It quickly gained traction as a robust solution for service discovery and configuration in microservices architectures and dynamic cloud environments. Over the years, it has evolved to include advanced features like a service mesh with Connect, expanded ACL capabilities, and improved multi-datacenter support, becoming a foundational component in many modern infrastructure stacks.