github.com/outbrain/consul@v1.4.5/website/source/docs/commands/index.html.md (about) 1 --- 2 layout: "docs" 3 page_title: "Commands" 4 sidebar_current: "docs-commands" 5 description: |- 6 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. 7 --- 8 9 # Consul Commands (CLI) 10 11 Consul is controlled via a very easy to use command-line interface (CLI). 12 Consul is only a single command-line application: `consul`. This application 13 then takes a subcommand such as "agent" or "members". The complete list of 14 subcommands is in the navigation to the left. 15 16 The `consul` CLI is a well-behaved command line application. In erroneous 17 cases, a non-zero exit status will be returned. It also responds to `-h` and `--help` 18 as you'd most likely expect. And some commands that expect input accept 19 "-" as a parameter to tell Consul to read the input from stdin. 20 21 To view a list of the available commands at any time, just run `consul` with 22 no arguments: 23 24 ```text 25 $ consul 26 Usage: consul [--version] [--help] <command> [<args>] 27 28 Available commands are: 29 agent Runs a Consul agent 30 catalog Interact with the catalog 31 connect Interact with Consul Connect 32 event Fire a new event 33 exec Executes a command on Consul nodes 34 force-leave Forces a member of the cluster to enter the "left" state 35 info Provides debugging information for operators. 36 intention Interact with Connect service intentions 37 join Tell Consul agent to join cluster 38 keygen Generates a new encryption key 39 keyring Manages gossip layer encryption keys 40 kv Interact with the key-value store 41 leave Gracefully leaves the Consul cluster and shuts down 42 lock Execute a command holding a lock 43 maint Controls node or service maintenance mode 44 members Lists the members of a Consul cluster 45 monitor Stream logs from a Consul agent 46 operator Provides cluster-level tools for Consul operators 47 reload Triggers the agent to reload configuration files 48 rtt Estimates network round trip time between nodes 49 services Interact with services 50 snapshot Saves, restores and inspects snapshots of Consul server state 51 validate Validate config files/directories 52 version Prints the Consul version 53 watch Watch for changes in Consul 54 ``` 55 56 To get help for any specific command, pass the `-h` flag to the relevant 57 subcommand. For example, to see help about the `join` subcommand: 58 59 ```text 60 $ consul join -h 61 Usage: consul join [options] address ... 62 63 Tells a running Consul agent (with "consul agent") to join the cluster 64 by specifying at least one existing member. 65 66 HTTP API Options 67 68 -http-addr=<address> 69 The `address` and port of the Consul HTTP agent. The value can be 70 an IP address or DNS address, but it must also include the port. 71 This can also be specified via the CONSUL_HTTP_ADDR environment 72 variable. The default value is http://127.0.0.1:8500. The scheme 73 can also be set to HTTPS by setting the environment variable 74 CONSUL_HTTP_SSL=true. 75 76 -token=<value> 77 ACL token to use in the request. This can also be specified via the 78 CONSUL_HTTP_TOKEN environment variable. If unspecified, the query 79 will default to the token of the Consul agent at the HTTP address. 80 81 Command Options 82 83 -wan 84 Joins a server to another server in the WAN pool. 85 ``` 86 87 ## Autocompletion 88 89 The `consul` command features opt-in subcommand autocompletion that you can 90 enable for your shell with `consul -autocomplete-install`. After doing so, 91 you can invoke a new shell and use the feature. 92 93 For example, assume a tab is typed at the end of each prompt line: 94 95 ``` 96 $ consul e 97 event exec 98 99 $ consul r 100 reload rtt 101 102 $ consul operator raft 103 list-peers remove-peer 104 ``` 105 106 ## Environment Variables 107 108 In addition to CLI flags, Consul reads environment variables for behavior 109 defaults. CLI flags always take precedence over environment variables, but it 110 is often helpful to use environment variables to configure the Consul agent, 111 particularly with configuration management and init systems. 112 113 These environment variables and their purpose are described below: 114 115 ## `CONSUL_HTTP_ADDR` 116 117 This is the HTTP API address to the *local* Consul agent 118 (not the remote server) specified as a URI with optional scheme: 119 120 ``` 121 CONSUL_HTTP_ADDR=127.0.0.1:8500 122 ``` 123 124 or as a Unix socket path: 125 126 ``` 127 CONSUL_HTTP_ADDR=unix://var/run/consul_http.sock 128 ``` 129 130 If the `https://` scheme is used, `CONSUL_HTTP_SSL` is implied to be true. 131 132 ### `CONSUL_HTTP_TOKEN` 133 134 This is the API access token required when access control lists (ACLs) 135 are enabled, for example: 136 137 ``` 138 CONSUL_HTTP_TOKEN=aba7cbe5-879b-999a-07cc-2efd9ac0ffe 139 ``` 140 141 ### `CONSUL_HTTP_AUTH` 142 143 This specifies HTTP Basic access credentials as a username:password pair: 144 145 ``` 146 CONSUL_HTTP_AUTH=operations:JPIMCmhDHzTukgO6 147 ``` 148 149 ### `CONSUL_HTTP_SSL` 150 151 This is a boolean value (default is false) that enables the HTTPS URI 152 scheme and SSL connections to the HTTP API: 153 154 ``` 155 CONSUL_HTTP_SSL=true 156 ``` 157 158 ### `CONSUL_HTTP_SSL_VERIFY` 159 160 This is a boolean value (default true) to specify SSL certificate verification; 161 setting this value to `false` is not recommended for production use. Example for 162 development purposes: 163 164 ``` 165 CONSUL_HTTP_SSL_VERIFY=false 166 ``` 167 168 ### `CONSUL_CACERT` 169 170 Path to a CA file to use for TLS when communicating with Consul. 171 172 ``` 173 CONSUL_CACERT=ca.crt 174 ``` 175 176 ### `CONSUL_CAPATH` 177 178 Path to a directory of CA certificates to use for TLS when communicating with Consul. 179 180 ``` 181 CONSUL_CAPATH=ca_certs/ 182 ``` 183 184 ### `CONSUL_CLIENT_CERT` 185 186 Path to a client cert file to use for TLS when `verify_incoming` is enabled. 187 188 ``` 189 CONSUL_CLIENT_CERT=client.crt 190 ``` 191 192 ### `CONSUL_CLIENT_KEY` 193 194 Path to a client key file to use for TLS when `verify_incoming` is enabled. 195 196 ``` 197 CONSUL_CLIENT_KEY=client.key 198 ``` 199 200 ### `CONSUL_TLS_SERVER_NAME` 201 202 The server name to use as the SNI host when connecting via TLS. 203 204 ``` 205 CONSUL_TLS_SERVER_NAME=consulserver.domain 206 ``` 207 208 ### `CONSUL_GRPC_ADDR` 209 210 Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the 211 local agent is listening for gRPC requests. Currently gRPC is only used for 212 integrating [Envoy proxy](/docs/connect/proxies/envoy.html) and must be [enabled 213 explicitly](/docs/agent/options.html#grpc_port) in agent configuration. 214 215 ``` 216 CONSUL_GRPC_ADDR=127.0.0.1:8502 217 ``` 218 219 or as a Unix socket path: 220 221 ``` 222 CONSUL_GRPC_ADDR=unix://var/run/consul_grpc.sock 223 ``` 224 225 If the agent is [configured with TLS 226 certificates](/docs/agent/encryption.html#rpc-encryption-with-tls), then the 227 gRPC listener will require TLS and present the same certificate as the https 228 listener. As with `CONSUL_HTTP_ADDR`, if TLS is enabled either the `https://` 229 scheme should be used, or `CONSUL_HTTP_SSL` set.