-> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](/docs/agent/config/agent-config-files#config_key_reference) for equivalent HCL Keys.
- `-client` ((#\_client)) - The address to which Consul will bind client
interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1",
allowing only loopback connections. In Consul 1.0 and later this can be set to
a space-separated list of addresses to bind to, or a [go-sockaddr]
template that can potentially resolve to multiple addresses.
- `-data-dir` ((#\_data_dir)) - This flag provides a data directory for
the agent to store state. This is required for all agents. The directory should
be durable across reboots. This is especially critical for agents that are running
in server mode as they must be able to persist cluster state. Additionally, the
directory must support the use of filesystem locking, meaning some types of mounted
folders (e.g. VirtualBox shared folders) may not be suitable.
**Note:** both server and non-server agents may store ACL tokens in the state in this directory so read access may grant access to any tokens on servers and to any tokens used during service registration on non-servers. On Unix-based platforms the files are written with 0600 permissions so you should ensure only trusted processes can execute as the same user as Consul. On Windows, you should ensure the directory has suitable permissions configured as these will be inherited.
- `-datacenter` ((#\_datacenter)) - This flag controls the datacenter in
which the agent is running. If not provided, it defaults to "dc1". Consul has first-class
support for multiple datacenters, but it relies on proper configuration. Nodes
in the same datacenter should be on a single LAN.
- `-dev` ((#\_dev)) - Enable development server mode. This is useful for
quickly starting a Consul agent with all persistence options turned off, enabling
an in-memory server which can be used for rapid prototyping or developing against
the API. In this mode, [Connect is enabled](/docs/connect/configuration) and
will by default create a new root CA certificate on startup. This mode is **not**
intended for production use as it does not write any data to disk. The gRPC port
is also defaulted to `8502` in this mode.
- `-disable-keyring-file` ((#\_disable_keyring_file)) - If set, the keyring
will not be persisted to a file. Any installed keys will be lost on shutdown, and
only the given `-encrypt` key will be available on startup. This defaults to false.
- `-enable-script-checks` ((#\_enable_script_checks)) This controls whether
[health checks that execute scripts](/docs/agent/checks) are enabled on this
agent, and defaults to `false` so operators must opt-in to allowing these. This
was added in Consul 0.9.0.
~> **Security Warning:** Enabling script checks in some configurations may
introduce a remote execution vulnerability which is known to be targeted by
malware. We strongly recommend `-enable-local-script-checks` instead. See [this
blog post](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations)
Like [`enable_script_checks`](#_enable_script_checks), but only enable them when
they are defined in the local configuration files. Script checks defined in HTTP
API registrations will still not be allowed.
- `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption
of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The
easiest way to create an encryption key is to use [`consul keygen`](/commands/keygen).
All nodes within a cluster must share the same encryption key to communicate. The
provided key is automatically persisted to the data directory and loaded automatically
whenever the agent is restarted. This means that to encrypt Consul's gossip protocol,
this option only needs to be provided once on each agent's initial startup sequence.
If it is provided after Consul has been initialized with an encryption key, then
the provided key is ignored and a warning will be displayed.
- `-grpc-port` ((#\_grpc_port)) - the gRPC API port to listen on. Default
-1 (gRPC disabled). See [ports](#ports) documentation for more detail.
- `-hcl` ((#\_hcl)) - A HCL configuration fragment. This HCL configuration
fragment is appended to the configuration and allows to specify the full range
of options of a config file on the command line. This option can be specified multiple
times. This was added in Consul 1.0.
- `-http-port` ((#\_http_port)) - the HTTP API port to listen on. This overrides
the default port 8500. This option is very useful when deploying Consul to an environment
which communicates the HTTP port through the environment e.g. PaaS like CloudFoundry,
allowing you to set the port directly via a Procfile.
- `-https-port` ((#\_https_port)) - the HTTPS API port to listen on. Default
-1 (https disabled). See [ports](#ports) documentation for more detail.
- `-default-query-time` ((#\_default_query_time)) - This flag controls the
amount of time a blocking query will wait before Consul will force a response.
This value can be overridden by the `wait` query parameter. Note that Consul applies
some jitter on top of this time. Defaults to 300s.
- `-max-query-time` ((#\_max_query_time)) - this flag controls the maximum
amount of time a blocking query can wait before Consul will force a response. Consul
applies jitter to the wait time. The jittered time will be capped to this time.
Defaults to 600s.
- `-pid-file` ((#\_pid_file)) - This flag provides the file path for the
agent to store its PID. This is useful for sending signals (for example, `SIGINT`
to close the agent or `SIGHUP` to update check definitions) to the agent.
- `-protocol` ((#\_protocol)) - The Consul protocol version to use. Consul
agents speak protocol 2 by default, however agents will automatically use protocol > 2 when speaking to compatible agents. This should be set only when [upgrading](/docs/upgrading). You can view the protocol versions supported by Consul by running `consul -v`.
- `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version
of the Raft consensus protocol used for server communications. This must be set
to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](/docs/agent/config/agent-config-files#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrade-specific#raft-protocol-version-compatibility) for more details.
This can also be set on client agents when used in combination with the [`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs) configuration option. By default, the [`-advertise`](#_advertise) address
accessed from a remote datacenter if the remote datacenter is configured with [`translate_wan_addrs`](/docs/agent/config/agent-config-files#translate_wan_addrs). In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
IPv6 address. If there are multiple public IPv6 addresses available, Consul will
exit with an error at startup. Consul uses both TCP and UDP and the same port for
both. If you have any firewalls, be sure to allow both protocols. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
template that must resolve at runtime to a single address. Some example templates:
```shell
# Using address within a specific CIDR
$ consul agent -bind '{{ GetPrivateInterfaces | include "network" "10.0.0.0/8" | attr "address" }}'
```
```shell
# Using a static network interface name
$ consul agent -bind '{{ GetInterfaceIP "eth0" }}'
```
```shell
# Using regular expression matching for network interface name that is forwardable and up
$ consul agent -bind '{{ GetAllInterfaces | include "name" "^eth" | include "flags" "forwardable|up" | attr "address" }}'
```
- `-serf-wan-bind` ((#\_serf_wan_bind)) - The address that should be bound
to for Serf WAN gossip communications. By default, the value follows the same rules
as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind`
option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
template that is resolved at runtime.
- `-serf-lan-bind` ((#\_serf_lan_bind)) - The address that should be bound
to for Serf LAN gossip communications. This is an IP address that should be reachable
by all other LAN nodes in the cluster. By default, the value follows the same rules
as [`-bind` command-line flag](#_bind), and if this is not specified, the `-bind`
option is used. This is available in Consul 0.7.1 and later. In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr]
template that is resolved at runtime.
## Bootstrap Options
- `-bootstrap` ((#\_bootstrap)) - This flag is used to control if a server
is in "bootstrap" mode. It is important that no more than one server **per** datacenter
be running in this mode. Technically, a server in bootstrap mode is allowed to
self-elect as the Raft leader. It is important that only a single node is in this
mode; otherwise, consistency cannot be guaranteed as multiple nodes are able to
self-elect. It is not recommended to use this flag after a cluster has been bootstrapped.
- `-bootstrap-expect` ((#\_bootstrap_expect)) - This flag provides the number
of expected servers in the datacenter. Either this value should not be provided
or the value must agree with other servers in the cluster. When provided, Consul
waits until the specified number of servers are available and then bootstraps the
cluster. This allows an initial leader to be elected automatically. This cannot
be used in conjunction with the legacy [`-bootstrap`](#_bootstrap) flag. This flag
requires [`-server`](#_server) mode.
## Configuration File Options
- `-config-file` ((#\_config_file)) - A configuration file to load. For
more information on the format of this file, read the [Configuration Files](#configuration_files)
section. This option can be specified multiple times to load multiple configuration
files. If it is specified multiple times, configuration files loaded later will
merge with configuration files loaded earlier. During a config merge, single-value
keys (string, int, bool) will simply have their values replaced while list types
will be appended together.
- `-config-dir` ((#\_config_dir)) - A directory of configuration files to
load. Consul will load all files in this directory with the suffix ".json" or ".hcl".
The load order is alphabetical, and the the same merge routine is used as with
the [`config-file`](#_config_file) option above. This option can be specified multiple
times to load multiple directories. Sub-directories of the config directory are
not loaded. For more information on the format of the configuration files, see
the [Configuration Files](#configuration_files) section.
- `-config-format` ((#\_config_format)) - The format of the configuration
files to load. Normally, Consul detects the format of the config files from the
".json" or ".hcl" extension. Setting this option to either "json" or "hcl" forces
Consul to interpret any file with or without extension to be interpreted in that
format.
## DNS and Domain Options
- `-dns-port` ((#\_dns_port)) - the DNS port to listen on. This overrides
the default port 8600. This is available in Consul 0.7 and later.
- `-domain` ((#\_domain)) - By default, Consul responds to DNS queries in
the "consul." domain. This flag can be used to change that domain. All queries
in this domain are assumed to be handled by Consul and will not be recursively
resolved.
- `-alt-domain` ((#\_alt_domain)) - This flag allows Consul to respond to
DNS queries in an alternate domain, in addition to the primary domain. If unset,
no alternate domain is used.
In Consul 1.10.4 and later, Consul DNS responses will use the same domain as in the query (`-domain` or `-alt-domain`) where applicable.
PTR query responses will always use `-domain`, since the desired domain cannot be included in the query.
- `-recursor` ((#\_recursor)) - Specifies the address of an upstream DNS
server. This option may be provided multiple times, and is functionally equivalent
to the [`recursors` configuration option](#recursors).
## Join Options
- `-join` ((#\_join)) - Address of another agent to join upon starting up.
This can be specified multiple times to specify multiple agents to join. If Consul
is unable to join with any of the specified addresses, agent startup will fail.
By default, the agent won't join any nodes when it starts up. Note that using [`retry_join`](#retry_join) could be more appropriate to help mitigate node startup race conditions when automating
a Consul cluster deployment.
In Consul 1.1.0 and later this can be dynamically defined with a
[go-sockaddr]
template that is resolved at runtime.
If using Enterprise network segments, see [additional documentation on
joining a client to a segment](/docs/enterprise/network-segments#join_a_client_to_a_segment).
- `-retry-join` ((#\_retry_join)) - Similar to [`-join`](#_join) but allows retrying a join until
it is successful. Once it joins successfully to a member in a list of members
it will never attempt to join again. Agents will then solely maintain their
membership via gossip. This is useful for cases where you know the address will
eventually be available. This option can be specified multiple times to
specify multiple agents to join. The value can contain IPv4, IPv6, or DNS
addresses. IPv6 must use the "bracketed" syntax. If multiple values
are given, they are tried and retried in the order listed until the first
succeeds.
In Consul 1.1.0 and later this can be dynamically defined with a
[go-sockaddr]
template that is resolved at runtime.
If Consul is running on the non-default Serf LAN port, the port must
be specified in the join address, or configured as the agent's default Serf port
