1--- 2layout: "docs" 3page_title: "Commands: Join" 4sidebar_current: "docs-commands-join" 5description: |- 6 The `serf join` command tells a Serf agent to join an existing cluster. A new Serf agent must join with at least one existing member of a cluster in order to join an existing cluster. After joining that one member, the gossip layer takes over, propagating the updated membership state across the cluster. 7--- 8 9# Serf Join 10 11Command: `serf join` 12 13The `serf join` command tells a Serf agent to join an existing cluster. 14A new Serf agent must join with at least one existing member of a cluster 15in order to join an existing cluster. After joining that one member, 16the gossip layer takes over, propagating the updated membership state across 17the cluster. 18 19If you don't join an existing cluster, then that agent is part of its own 20isolated cluster. Other nodes can join it. 21 22Agents can join other agents multiple times without issue. If a node that 23is already part of a cluster joins another node, then the clusters of the 24two nodes join to become a single cluster. 25 26## Usage 27 28Usage: `serf join [options] address ...` 29 30You may call join with multiple addresses if you want to try to join 31multiple clusters. Serf will attempt to join all clusters, and the join 32command will fail only if Serf was unable to join with any. 33 34The command-line flags are all optional. The list of available flags are: 35 36* `-replay` - If set, old user events from the past will be replayed for the 37 agent/cluster that is joining. Otherwise, past events will be ignored. 38 39* `-rpc-addr` - Address to the RPC server of the agent you want to contact 40 to send this command. If this isn't specified, the command will contact 41 "127.0.0.1:7373" which is the default RPC address of a Serf agent. This option 42 can also be controlled using the `SERF_RPC_ADDR` environment variable. 43 44* `-rpc-auth` - Optional RPC auth token. If the agent is configured to use 45 an auth token, then this must be provided or the agent will refuse the 46 command. This option can also be controlled using the `SERF_RPC_AUTH` 47 environment variable. 48 49## Replaying User Events 50 51When joining a cluster, the past events that were sent to the cluster are 52usually ignored. However, if you specify the `-replay` flag, then past events 53will be replayed on the joining cluster. 54 55Note that only a fixed amount of past events are stored. At the time of writing 56this documentation, that fixed amount is 1024 events. Therefore, if you replay 57events, you'll only receive the past 1024 events (if there are that many). 58