---
layout: commands
page_title: 'Commands: Operator Raft'
description: >
  The operator raft subcommand is used to view and modify Consul's Raft
  configuration.
---

# Consul Operator Raft

Command: `consul operator raft`

The Raft operator command is used to interact with Consul's Raft subsystem. The
command can be used to verify Raft peers or in rare cases to recover quorum by
removing invalid peers.

```text
Usage: consul operator raft <subcommand> [options]

The Raft operator command is used to interact with Consul's Raft subsystem. The
command can be used to verify Raft peers or in rare cases to recover quorum by
removing invalid peers.

Subcommands:

    list-peers     Display the current Raft peer configuration
    remove-peer    Remove a Consul server from the Raft configuration
```

## list-peers

Corresponding HTTP API Endpoint: [\[GET\] /v1/status/peers](/consul/api-docs/status#list-raft-peers)

This command displays the current Raft peer configuration.

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

| ACL Required |
| ------------ |
| `none`       |

Usage: `consul operator raft list-peers -stale=[true|false]`

The output looks like this:

```text
Node     ID              Address         State     Voter  RaftProtocol  Commit Index Trails Leader By
alice    127.0.0.1:8300  127.0.0.1:8300  follower  true   2             1167         0 commits
bob      127.0.0.2:8300  127.0.0.2:8300  leader    true   3             1167         -
carol    127.0.0.3:8300  127.0.0.3:8300  follower  true   2             1159         8 commits
```

`Node` is the node name of the server, as known to Consul, or "(unknown)" if
the node is stale and not known.

`ID` is the ID of the server. This is the same as the `Address` in Consul 0.7
but may be upgraded to a GUID in a future version of Consul.

`Address` is the IP:port for the server.

`State` is either "follower" or "leader" depending on the server's role in the
Raft configuration.

`Voter` is "true" or "false", indicating if the server has a vote in the Raft
configuration.

`Commit Index` is the last log index the server has a record of in its Raft log.

`Trails Leader By` is the number of commits a follower trails the leader by.

#### Command Options

- `-stale` - Enables non-leader servers to provide cluster state information.
  If the cluster is in an outage state without a leader,
  we recommend setting this option to `true`.
  Default is `false`.

## remove-peer

Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/raft/peer](/consul/api-docs/operator/raft#delete-raft-peer)

This command removes the Consul server with given address from the Raft configuration.

There are rare cases where a peer may be left behind in the Raft configuration
even though the server is no longer present and known to the cluster. This command
can be used to remove the failed server so that it is no longer affects the
Raft quorum. If the server still shows in the output of the
[`consul members`](/consul/commands/members) command, it is preferable to
clean up by simply running
[`consul force-leave`](/consul/commands/force-leave)
instead of this command.

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

| ACL Required     |
| ---------------- |
| `operator:write` |

Usage: `consul operator raft remove-peer -address="IP:port"`

- `-address` - "IP:port" for the server to remove. The port number is usually
  8300, unless configured otherwise.

- `-id` - ID of the server to remove.

The return code will indicate success or failure.

## transfer-leader

Corresponding HTTP API Endpoint: [\[POST\] /v1/operator/raft/transfer-leader](/consul/api-docs/operator/raft#transfer-raft-leadership)

This command transfers Raft leadership to another server agent. If an `id` is provided, Consul transfers leadership to the server with that id.

Use this command to change leadership without restarting the leader node, which maintains quorum and workload capacity.

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

| ACL Required     |
| ---------------- |
| `operator:write` |

Usage: `consul operator raft transfer-leader -id="server id"`

- `-id` - Specifies the node ID of the raft peer to transfer leadership to.
If empty, leadership transfers to a random server agent.

The return code indicates success or failure.