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-docs#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'