basectl: the Base node operator CLI

basectl is a command-line tool for running, monitoring, and debugging Base infrastructure. It gives you an interactive terminal dashboard and a set of scriptable commands to:

Inspect blocks, node sync, peers, the transaction pool, Flashblocks, and proofs.
Check node health with a single diagnostic command.
Operate high-availability (HA) sequencer clusters.

It works against mainnet, Sepolia (testnet), and local development networks.

basectl is built for node operators. If you only need an RPC endpoint to build an app, use a public endpoint or a node provider instead of running your own node.

Installation

Most operators install basectl with baseup, the installer for Base’s release binaries. It’s also included in the base/node Docker image, and you can build it from source.

Install with baseup (recommended)

baseup downloads and verifies the official release binaries. Install baseup, then install basectl:

Install basectl with baseup

# Install baseup
curl -fsSL https://raw.githubusercontent.com/base/base/main/baseup/install | bash

# Install just basectl (use --bin all for every Base binary)
baseup --bin basectl

Or build from source

basectl lives in the base/base repository. Build it with Cargo, using the same maxperf profile as the release binaries:

Build basectl

cargo build --profile maxperf --bin basectl

The compiled binary is written to target/maxperf/basectl.

Verify the install

Confirm the binary runs and prints its help:

Verify basectl

basectl --help

Usage

basectl syntax

basectl [OPTIONS] [COMMAND]

Global options

Flag	Default	Description
`-c, --config <CONFIG>`	`mainnet`	Which network to target: `mainnet`, `sepolia`, `devnet`, or a path to a config file.
`--conductor-rpc <URL>`		Starting point for finding the nodes in a sequencer cluster, used by `conductor` and `sequencer`. Only needed when the network config doesn’t list the cluster’s nodes. You can also set it with the `BASECTL_CONDUCTOR_RPC` environment variable.

Choosing a network

Pass -c/--config to pick which network a command runs against:

Config	Use for
`mainnet`	Base mainnet (default).
`sepolia`	Base Sepolia testnet.
`devnet`	A local development network.
`<path>`	Your own YAML config file.

By default, the mainnet and sepolia configs talk to a local node at http://127.0.0.1:8545 (execution layer) and http://127.0.0.1:9545 (consensus layer). They also keep the hosted public endpoints on hand for read-only comparisons, such as checking how far your node is behind the network. If your local node isn’t running, these commands report an error rather than quietly using the public endpoint. To point a command somewhere else, use the RPC flags on that command (--el-rpc, --cl-rpc, --conductor-rpc, --prover-rpc) or supply your own config file.

Output formats

Most read-only commands print an easy-to-read table by default and support two extra formats:

Flag	Description
`--json`	Print JSON with values already decoded for you — numbers in decimal, timestamps as readable dates, and a few precomputed fields. Good for scripting with tools like `jq`.
`--raw`	Add to `--json` to print the response exactly as the node returns it (hex values, original field names). Useful when you want to pass the output to other JSON-RPC tools such as `cast`. Using `--raw` without `--json` is an error.

Commands that change node state

Some commands change live infrastructure: banning or removing peers, clearing the transaction pool, pausing a conductor, starting or stopping a sequencer, and submitting proofs. These share the same safeguards:

They print exactly what they’re about to do and wait for you to type y or yes. Anything else (including pressing Enter) cancels the command.
Add --yes to skip the prompt when scripting.
Adding --json to one of these commands requires --yes, so an automated run never gets stuck waiting for input.
A command that acts on every node in a cluster can succeed on some nodes and fail on others. The output lists which nodes succeeded and which failed, and the command exits with an error if any node failed.

These commands act on live infrastructure. Target a specific node with the relevant RPC flag, and only pass --yes from automation you trust.

Commands

Command	Description
`monitor`	Interactive terminal dashboard for block production, sync, Flashblocks, data availability, conductor clusters, and upgrades.
`block`, `sync-status`, `flashblocks`	Read a single block, check how far your node is behind the network, and stream Flashblocks as JSON.
`p2p`	View peers and endpoints, and add, remove, ban, or unban peers.
`txpool`	View pending and queued transactions, and clear the pool.
`conductor`, `sequencer`	Operate high-availability sequencer clusters: check status, transfer leadership, pause, start, and stop.
`doctor`	Run read-only health checks across the execution layer, consensus layer, and L1.
`proofs`	Submit and check ZK proof requests to speed up finality for a range of blocks.

Beryl Upgrade

Introduction

Core Concepts

Node Operators

Network Reference

API Reference

Protocol Specifications

Security

basectl: the Base node operator CLI

Installation

Usage

Global options

Choosing a network

Output formats

Commands that change node state

Commands

​Installation

​Usage

​Global options

​Choosing a network

​Output formats

​Commands that change node state

​Commands

​Related

Installation

Usage

Global options

Choosing a network

Output formats

Commands that change node state

Commands

Related