> ## Documentation Index
> Fetch the complete documentation index at: https://base-a060aa97-mux-basectl-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage peers with basectl p2p

> View P2P endpoints and peers, test whether your node is reachable, and add, remove, ban, or unban execution-layer and consensus-layer peers on a Base node with basectl p2p.

`basectl p2p` lets you view and manage the peer connections for both the execution layer (EL) and the consensus layer (CL).

## Commands

* `basectl p2p info` shows your node's advertised endpoint and peer count for each layer (plus the CL's configured maximum peer count when the node reports it).
* `basectl p2p peers` lists the connected peers for each layer.
* `basectl p2p reachability <ENODE>` asks the Base telemetry service to try connecting to an EL node from the outside, so you can confirm your node is reachable.
* `basectl p2p add-peer <TARGET>` connects to one peer. An `enode://...` address connects an EL peer; an `enr:...` record or a `/.../p2p/<peer-id>` address connects a CL peer.
* `basectl p2p remove-peer <TARGET>` disconnects one peer. An `enode://...` address removes an EL peer; any other value is treated as a CL peer ID.
* `basectl p2p ban <TARGET>` bans one peer. An `enode://...` address bans an EL peer; a CL peer ID bans a CL peer. Banning a CL peer also tries to disconnect it right away.
* `basectl p2p unban <TARGET>` unbans one EL or CL peer using the same rules. It does not reconnect the peer.
* `basectl p2p unban-all` unbans every peer currently banned on the consensus layer.

## Flags

Read-only commands and single-peer actions accept:

| Flag             | Description                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `--el-rpc <URL>` | Use a specific execution-layer RPC URL instead of the one in your config. |
| `--cl-rpc <URL>` | Use a specific consensus-node RPC URL instead of the one in your config.  |

Read-only commands also accept:

| Flag     | Description                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------- |
| `--json` | Print JSON instead of a table.                                                                       |
| `--raw`  | Add to `--json` to print the raw response from the node. Using `--raw` without `--json` is an error. |

Commands that ban or remove peers also accept:

| Flag     | Description                                                                                                                             |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--yes`  | Skip the confirmation prompt. By default these commands print exactly what they'll do and wait for `y` or `yes`; anything else cancels. |
| `--json` | Print the result as JSON. Requires `--yes` so an automated run never waits for input.                                                   |

## Testing reachability

`p2p reachability` first detects which network your node is on, then asks the hosted Base mainnet or Sepolia telemetry service to connect to the node you name. The command supports `--json` and exits with an error if the connection doesn't fully succeed, so you can use it in scripts.

The `stage` field tells you how far the connection got:

| Stage                 | Meaning                                                        |
| --------------------- | -------------------------------------------------------------- |
| `tcp_connect`         | Opening a TCP connection to the node's advertised address.     |
| `encrypted_handshake` | Setting up the encrypted connection using the node's identity. |
| `devp2p_hello`        | Exchanging the initial Ethereum P2P handshake message.         |

## What your EL RPC needs to expose

Some P2P actions require an EL RPC with **admin methods** enabled. When those methods aren't available, `basectl p2p` still runs but some fields and actions won't work.

<Warning>
  If your EL RPC doesn't expose admin methods, peer counts still work, but endpoint details, peer listings, and EL bans do not.
</Warning>

* Peer counts come from `net_peerCount`, which works on most RPCs, including restricted or public ones.
* Endpoint details and peer listings need the EL admin methods `admin_nodeInfo` and `admin_peers`. Without them, the peer count still shows, but endpoint fields and peer lists appear as unavailable.
* EL bans and unbans use `admin_banPeer` and `admin_unbanPeer`. In reth, a "trusted" peer can't be banned until it's removed from the trusted set; reth silently ignores such bans, so `basectl p2p ban` checks first and fails clearly if the target is a currently connected trusted peer.
* CL data and bans use the consensus node's P2P methods (`opp2p_*`).
* `unban-all` is CL-only, because the EL admin API has no way to list banned peers.

## Examples

```bash View peers theme={null}
# Endpoint and peer-count summary
basectl -c sepolia p2p info

# List peers as JSON
basectl -c sepolia p2p peers --json | jq '{el: .el | length, cl: .cl | length}'

# Test whether an EL node is reachable from the outside
basectl -c sepolia p2p reachability enode://<node-id>@203.0.113.10:30303 --json

# On a restricted EL RPC, peer count still works but some fields may be unavailable
basectl -c sepolia p2p info --el-rpc https://your-el.example/ --cl-rpc https://your-cl.example/
```

```bash Manage peers theme={null}
# Add an EL peer (asks for confirmation first)
basectl -c sepolia p2p add-peer enode://<node-id>@203.0.113.10:30303 --el-rpc https://your-el.example/

# Add a CL peer without a prompt and print JSON
basectl -c sepolia p2p add-peer enr:<record> --cl-rpc https://your-cl.example/ --yes --json | jq .

# Remove a CL peer by its peer ID
basectl -c sepolia p2p remove-peer 16Uiu2HAm... --cl-rpc https://your-cl.example/

# Ban an EL peer (needs an admin-enabled EL RPC)
basectl -c sepolia p2p ban enode://<node-id>@203.0.113.10:30303 --el-rpc https://your-el.example/

# Ban a CL peer and disconnect it immediately
basectl -c sepolia p2p ban 16Uiu2HAm... --cl-rpc https://your-cl.example/

# Unban a CL peer without a prompt and print JSON
basectl -c sepolia p2p unban 16Uiu2HAm... --cl-rpc https://your-cl.example/ --yes --json | jq .

# Unban every currently banned CL peer
basectl -c sepolia p2p unban-all --cl-rpc https://your-cl.example/ --yes
```

## Related

* [basectl overview](/base-chain/node-operators/basectl/overview)
* [Diagnose node health](/base-chain/node-operators/basectl/doctor)
* [Node troubleshooting](/base-chain/node-operators/troubleshooting)