Consul Commands (CLI)

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:

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
HTTP API Options
  -http-addr=<address>
     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 http://127.0.0.1:8500. The scheme
     can also be set to HTTPS by setting the environment variable
     CONSUL_HTTP_SSL=true.
  -token=<value>
     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
  -wan

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:

CONSUL_HTTP_ADDR=127.0.0.1:8500

or as a Unix socket path:

CONSUL_HTTP_ADDR=unix:///var/run/consul_http.sock

If the scheme is used, CONSUL_HTTP_SSL is implied to be true.

CONSUL_HTTP_TOKEN

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

CONSUL_HTTP_TOKEN=aba7cbe5-879b-999a-07cc-2efd9ac0ffe

CONSUL_HTTP_TOKEN_FILE

This is a path to a file containing the API access token required when access control lists (ACLs) are enabled, for example:

CONSUL_HTTP_AUTH

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

CONSUL_HTTP_AUTH=operations:JPIMCmhDHzTukgO6

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

CONSUL_HTTP_SSL=true

CONSUL_HTTP_SSL_VERIFY

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:

CONSUL_HTTP_SSL_VERIFY=false

CONSUL_CACERT

CONSUL_CACERT=ca.crt

CONSUL_CAPATH

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

CONSUL_CAPATH=ca_certs/

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

CONSUL_CLIENT_KEY

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

CONSUL_CLIENT_KEY=client.key

CONSUL_TLS_SERVER_NAME

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

CONSUL_TLS_SERVER_NAME=consulserver.domain

CONSUL_GRPC_ADDR

Like CONSUL_HTTP_ADDR but configures the address the local agent is listening for gRPC requests. Currently gRPC is only used for integrating and must be enabled explicitly in agent configuration.

CONSUL_GRPC_ADDR=127.0.0.1:8502

or as a Unix socket path:

If the agent is , then the gRPC listener will require TLS and present the same certificate as the https listener. As with CONSUL_HTTP_ADDR, if TLS is enabled either the https:// scheme should be used, or CONSUL_HTTP_SSL set.

CONSUL_NAMESPACE=default