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:

    1. $ consul
    2. Usage: consul [--version] [--help] <command> [<args>]
    4. Available commands are:
    5.     acl            Interact with Consul's ACLs
    6.     agent          Runs a Consul agent
    7.     catalog        Interact with the catalog
    8.     connect        Interact with Consul Connect
    9.     debug          Records a debugging archive for operators
    10.     event          Fire a new event
    11.     exec           Executes a command on Consul nodes
    12.     force-leave    Forces a member of the cluster to enter the "left" state
    13.     info           Provides debugging information for operators.
    14.     intention      Interact with Connect service intentions
    15.     join           Tell Consul agent to join cluster
    16.     keygen         Generates a new encryption key
    17.     keyring        Manages gossip layer encryption keys
    18.     kv             Interact with the key-value store
    19.     leave          Gracefully leaves the Consul cluster and shuts down
    20.     lock           Execute a command holding a lock
    21.     login          Login to Consul using an auth method
    22.     logout         Destroy a Consul token created with login
    23.     maint          Controls node or service maintenance mode
    24.     members        Lists the members of a Consul cluster
    25.     monitor        Stream logs from a Consul agent
    26.     operator       Provides cluster-level tools for Consul operators
    27.     reload         Triggers the agent to reload configuration files
    28.     rtt            Estimates network round trip time between nodes
    29.     services       Interact with services
    30.     snapshot       Saves, restores and inspects snapshots of Consul server state
    31.     validate       Validate config files/directories
    32.     version        Prints the Consul version
    33.     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:

    1. $ consul join --help
    2. Usage: consul join [options] address ...
    5.   by specifying at least one existing member.
    7. HTTP API Options
    9.   -http-addr=<address>
    10.      The `address` and port of the Consul HTTP agent. The value can be
    11.      an IP address or DNS address, but it must also include the port.
    12.      This can also be specified via the CONSUL_HTTP_ADDR environment
    13.      variable. The default value is http://127.0.0.1:8500. The scheme
    14.      can also be set to HTTPS by setting the environment variable
    15.      CONSUL_HTTP_SSL=true.
    17.   -token=<value>
    18.      ACL token to use in the request. This can also be specified via the
    19.      CONSUL_HTTP_TOKEN environment variable. If unspecified, the query
    20.      will default to the token of the Consul agent at the HTTP address.
    22. Command Options
    24.   -wan
    25.      Joins a server to another server in the WAN pool.
    1. $ consul join --help
    2. Usage: consul join [options] address ...
    4.   Tells a running Consul agent (with "consul agent") to join the cluster
    5.   by specifying at least one existing member.
    7. HTTP API Options
    9.   -http-addr=<address>
    10.      The `address` and port of the Consul HTTP agent. The value can be
    11.      an IP address or DNS address, but it must also include the port.
    12.      This can also be specified via the CONSUL_HTTP_ADDR environment
    13.      variable. The default value is http://127.0.0.1:8500. The scheme
    14.      can also be set to HTTPS by setting the environment variable
    15.      CONSUL_HTTP_SSL=true.
    17.   -token=<value>
    18.      ACL token to use in the request. This can also be specified via the
    19.      CONSUL_HTTP_TOKEN environment variable. If unspecified, the query
    21. Command Options
    23.   -wan
    24.      Joins a server to another server in the WAN pool.

    When the ACL system is enabled the Consul CLI will require an to perform API requests.

    The ACL token can be provided directly on the command line using the -token command line flag, from a file using the -token-file command line flag, or from the CONSUL_HTTP_TOKEN environment variable.

    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:

    1. $ consul e
    2. event  exec
    4. $ consul r
    5. reload  rtt
    8. list-peers   remove-peer
    1. $ consul e
    2. event  exec
    4. $ consul r
    5. reload  rtt
    7. $ consul operator raft
    8. list-peers   remove-peer

    The CLI automatically URL-encodes arguments, which are then . To avoid double-encoding arguments, do not URL-encode arguments passed to the CLI.

    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 with optional scheme:

    1. CONSUL_HTTP_ADDR=127.0.0.1:8500
    1. CONSUL_HTTP_ADDR=127.0.0.1:8500

    or as a Unix socket path:

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

    If the https:// 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:

    1. CONSUL_HTTP_TOKEN=aba7cbe5-879b-999a-07cc-2efd9ac0ffe
    1. 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:

    1. CONSUL_HTTP_TOKEN_FILE=/path/to/consul.token

    CONSUL_HTTP_AUTH

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

    1. CONSUL_HTTP_AUTH=operations:JPIMCmhDHzTukgO6
    1. 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:

    1. CONSUL_HTTP_SSL=true
    1. CONSUL_HTTP_SSL=true

    CONSUL_HTTP_SSL_VERIFY

    1. CONSUL_HTTP_SSL_VERIFY=false
    1. CONSUL_HTTP_SSL_VERIFY=false

    CONSUL_CACERT

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

    1. CONSUL_CACERT=ca.crt
    1. CONSUL_CACERT=ca.crt

    CONSUL_CAPATH

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

    1. CONSUL_CAPATH=ca_certs/
    1. CONSUL_CAPATH=ca_certs/

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

    1. CONSUL_CLIENT_CERT=client.crt

    CONSUL_CLIENT_KEY

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

    1. CONSUL_CLIENT_KEY=client.key
    1. CONSUL_CLIENT_KEY=client.key

    CONSUL_TLS_SERVER_NAME

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

    1. CONSUL_TLS_SERVER_NAME=consulserver.domain
    1. CONSUL_TLS_SERVER_NAME=consulserver.domain

    CONSUL_GRPC_ADDR

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

    1. CONSUL_GRPC_ADDR=127.0.0.1:8502
    1. CONSUL_GRPC_ADDR=127.0.0.1:8502

    or as a Unix socket path:

    1. CONSUL_GRPC_ADDR=unix://var/run/consul_grpc.sock
    1. CONSUL_GRPC_ADDR=unix://var/run/consul_grpc.sock

    If the agent is configured with TLS certificates, 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.

      1. CONSUL_NAMESPACE=default