» Consul Commands (CLI)

Consul is controlled via a very easy to use command-line interface (CLI). Consul is only a single command-line application: consul. This application then takes a subcommand such as "agent" or "members". The complete list of subcommands is in the navigation to the left.

The consul CLI is a well-behaved command line application. In erroneous cases, a non-zero exit status will be returned. It also responds to -h and --help as you'd most likely expect. And some commands that expect input accept "-" as a parameter to tell Consul to read the input from stdin.

To view a list of the available commands at any time, just run consul with no arguments:

$ consul
usage: consul [--version] [--help] <command> [<args>]

Available commands are:
    agent          Runs a Consul agent
    configtest     Validate config file
    event          Fire a new event
    exec           Executes a command on Consul nodes
    force-leave    Forces a member of the cluster to enter the "left" state
    info           Provides debugging information for operators
    join           Tell Consul agent to join cluster
    keygen         Generates a new encryption key
    keyring        Manages gossip layer encryption keys
    kv             Interact with the KV store
    leave          Gracefully leaves the Consul cluster and shuts down
    lock           Execute a command holding a lock
    maint          Controls node or service maintenance mode
    members        Lists the members of a Consul cluster
    monitor        Stream logs from a Consul agent
    operator       Provides cluster-level tools for Consul operators
    reload         Triggers the agent to reload configuration files
    rtt            Estimates network round trip time between nodes
    version        Prints the Consul version
    watch          Watch for changes in Consul

To get help for any specific command, pass the -h flag to the relevant subcommand. For example, to see help about the join subcommand:

$ consul join -h
Usage: consul join [options] address ...

  Tells a running Consul agent (with "consul agent") to join the cluster
  by specifying at least one existing member.

HTTP API Options

     The `address` and port of the Consul HTTP agent. The value can be
     an IP address or DNS address, but it must also include the port.
     This can also be specified via the CONSUL_HTTP_ADDR environment
     variable. The default value is The scheme
     can also be set to HTTPS by setting the environment variable

     ACL token to use in the request. This can also be specified via the
     CONSUL_HTTP_TOKEN environment variable. If unspecified, the query
     will default to the token of the Consul agent at the HTTP address.

Command Options

     Joins a server to another server in the WAN pool.

» Autocompletion

The consul command features opt-in subcommand autocompletion that you can enable for your shell with consul -autocomplete-install. After doing so, you can invoke a new shell and use the feature.

For example, assume a tab is typed at the end of each prompt line:

$ consul e
event  exec

$ consul r
reload  rtt

$ consul operator raft
list-peers   remove-peer

» Environment Variables

In addition to CLI flags, Consul reads environment variables for behavior defaults. CLI flags always take precedence over environment variables, but it is often helpful to use environment variables to configure the Consul agent, particularly with configuration management and init systems.

These environment variables and their purpose are described below:


This is the HTTP API address to the local Consul agent (not the remote server) specified as a URI:


or as a Unix socket path:



This is the API access token required when access control lists (ACLs) are enabled, for example:



This specifies HTTP Basic access credentials as a username:password pair:



This is a boolean value (default is false) that enables the HTTPS URI scheme and SSL connections to the HTTP API:



This is a boolean value (default true) to specify SSL certificate verification; setting this value to false is not recommended for production use. Example for development purposes:



Path to a CA file to use for TLS when communicating with Consul.



Path to a directory of CA certificates to use for TLS when communicating with Consul.



Path to a client cert file to use for TLS when verify_incoming is enabled.



Path to a client key file to use for TLS when verify_incoming is enabled.



The server name to use as the SNI host when connecting via TLS.