open-consul/website/content/commands/join.mdx

---
layout: commands
page_title: 'Commands: Join'
description: >-
  The `join` command tells a Consul agent to join an existing cluster. A new
  Consul agent may join any node in the existing cluster. After joining with one
  member, the gossip communication will propagate the updated membership state
  across the cluster.
---

# Consul Join

Command: `consul join`

Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/join/:address](/api-docs/agent#join-agent)

The `join` command tells a Consul agent to join an existing cluster.
A new Consul agent may join any node in the existing cluster. After joining
with one member, the gossip communication will propagate the updated membership
state across the cluster.

An agent which is already part of a cluster may join an agent in a different
cluster, causing the two clusters to be merged into a single cluster.

The table below shows this command's [required ACLs](/api#authentication). Configuration of
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.

| ACL Required  |
| ------------- |
| `agent:write` |

## Usage

Usage: `consul join [options] address ...`

You may call `join` with multiple addresses if you want attempt to join the cluster
through multiple nodes. Consul will attempt to join all addresses. The join
command will fail only if Consul was unable to join any of the specified addresses.

#### Command Options

- `-wan` - For agents running in server mode, the agent will attempt to join
  other servers gossiping in a WAN cluster. This is used to form a bridge between
  multiple datacenters.

#### API Options

@include 'http_api_options_client.mdx'
website: bulk copy from serf 2014-02-08 00:41:03 +00:00			`---`
docs: update structure (#8506) - moved and renamed files/folders based on new structure - updated docs navigation based on new structure - moved CLI to top nav (created commands.jsx and commands-navigation.js) - updated and added redirects - updating to be consistent with standalone categories - changing "overview" link in top nav to lead to where intro was moved (docs/intro) - adding redirects for intro content - deleting old intro folders - format all data/navigation files - deleting old commands folder - reverting changes to glossary page - adjust intro navigation for removal of 'vs' paths - add helm page redirect - fix more redirects - add a missing redirect - fix broken anchor links and formatting mistakes - deleted duplicate section, added redirect, changed link - removed duplicate glossary page 2020-09-01 15:14:13 +00:00			`layout: commands`
intro and api navigation converted 2020-04-07 18:55:19 +00:00			`page_title: 'Commands: Join'`
website/docs: small doc improvements to CLI reference Small improvements to the join docs. The help text for `lock` says -try is deprecated and replaced with -timeout. Update the docs to match. 2020-03-16 21:54:45 +00:00			`description: >-`
intro and api navigation converted 2020-04-07 18:55:19 +00:00			The `join` command tells a Consul agent to join an existing cluster. A new
			`Consul agent may join any node in the existing cluster. After joining with one`
			`member, the gossip communication will propagate the updated membership state`
			`across the cluster.`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00			`---`

website: updating documentation on commands 2014-02-19 01:32:13 +00:00			`# Consul Join`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00
website: updating documentation on commands 2014-02-19 01:32:13 +00:00			Command: `consul join`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00
Fixed absolute links to HTTP apis. 2022-01-11 13:26:58 +00:00			`Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/join/:address](/api-docs/agent#join-agent)`
Added Corresponding HTTP API Endpoints for every CLI command 2022-01-10 17:40:11 +00:00
Use new Markdown syntaxes and add SEO descriptions 2014-10-19 23:40:10 +00:00			The `join` command tells a Consul agent to join an existing cluster.
website/docs: small doc improvements to CLI reference Small improvements to the join docs. The help text for `lock` says -try is deprecated and replaced with -timeout. Update the docs to match. 2020-03-16 21:54:45 +00:00			`A new Consul agent may join any node in the existing cluster. After joining`
			`with one member, the gossip communication will propagate the updated membership`
			`state across the cluster.`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00
website/docs: small doc improvements to CLI reference Small improvements to the join docs. The help text for `lock` says -try is deprecated and replaced with -timeout. Update the docs to match. 2020-03-16 21:54:45 +00:00			`An agent which is already part of a cluster may join an agent in a different`
			`cluster, causing the two clusters to be merged into a single cluster.`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00
Added ACL requirements for CLI commands 2022-01-10 21:44:56 +00:00			`The table below shows this command's [required ACLs](/api#authentication). Configuration of`
website: redirect /api to /api-docs (#12660) 2022-03-30 21:16:26 +00:00			`[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)`
Added ACL requirements for CLI commands 2022-01-10 21:44:56 +00:00			`are not supported from commands, but may be from the corresponding HTTP endpoint.`

			`\| ACL Required \|`
			`\| ------------- \|`
			\| `agent:write` \|

website: bulk copy from serf 2014-02-08 00:41:03 +00:00			`## Usage`

website: updating documentation on commands 2014-02-19 01:32:13 +00:00			Usage: `consul join [options] address ...`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00
docs: Clarify docs for providing multiple join addresses Rephrase the comment about specifying multiple join addresses to clarify that it pertains to joining a single cluster by attempting to contact one or more nodes. 2022-01-26 21:01:57 +00:00			You may call `join` with multiple addresses if you want attempt to join the cluster
			`through multiple nodes. Consul will attempt to join all addresses. The join`
			`command will fail only if Consul was unable to join any of the specified addresses.`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00
Convert join command to use base.Command 2017-02-08 22:14:02 +00:00			`#### Command Options`
website: bulk copy from serf 2014-02-08 00:41:03 +00:00
intro and api navigation converted 2020-04-07 18:55:19 +00:00			- `-wan` - For agents running in server mode, the agent will attempt to join
website: updating documentation on commands 2014-02-19 01:32:13 +00:00			`other servers gossiping in a WAN cluster. This is used to form a bridge between`
			`multiple datacenters.`
docs: show CLI cmd-specific opts before general opts Applied to all remaining CLI commands. 2022-07-27 06:17:11 +00:00
			`#### API Options`

			`@include 'http_api_options_client.mdx'`