consul/website/pages/commands/join.mdx

---
layout: commands
page_title: 'Commands: Join'
sidebar_title: 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`

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.

## Usage

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

You may call join with multiple addresses if you want to try to join
multiple clusters. Consul will attempt to join all addresses, and the join
command will fail only if Consul was unable to join with any.

#### API Options

@include 'http_api_options_client.mdx'

#### 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.
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'`
remove 'sidebar_current' from frontmatter 2020-04-13 18:40:26 +00:00			`sidebar_title: 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
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
			`## 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
			`You may call join with multiple addresses if you want to try to join`
website: updating documentation on commands 2014-02-19 01:32:13 +00:00			`multiple clusters. Consul will attempt to join all addresses, and the join`
			`command will fail only if Consul was unable to join with any.`
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			`#### API Options`

intro and api navigation converted 2020-04-07 18:55:19 +00:00			`@include 'http_api_options_client.mdx'`
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.`