Skip to main content

prysmctl

prysmctl is Prysm's tool for one-off operator tasks. For step-by-step guides, see:

Generated from Prysm v7.3.1. Each flag name is a permalink you can share. Press / to filter.

Subcommands

prysmctl checkpoint-sync download

Download the latest finalized state and the most recent block it integrates. To be used for checkpoint sync.

--beacon-node-host=<string>

host:port for beacon node connection

Beacon node REST API to download the finalized state and block from, as a URL or host:port (then http:// is assumed). Use a node you trust: the files become the starting point of your own node.

prysmctl checkpoint-sync download --beacon-node-host=https://<TRUSTED_BEACON_NODE>

default localhost:3500

--http-timeout=<duration>

timeout for http requests made to beacon-node-url (uses duration format, ex: 2m31s). default: 4m

Timeout for each HTTP request, as a Go duration. Mainnet states are several hundred megabytes, so raise it on slow links.

--http-timeout=10m

default 4m0s

prysmctl db query

database query tool

--bucket=<string>

boltdb bucket to search

Name of the BoltDB bucket to scan, for example blocks or state. List the names with prysmctl db buckets.

--path=<string>

path to directory containing beaconchain.db

Path to the BoltDB file itself, typically <datadir>/beaconchaindata/beaconchain.db, despite the flag description mentioning a directory. Stop the beacon node first: the command gives up after one second if the database is locked.

The file is opened read-write, and a missing file is created empty. Work on a copy if you are unsure.

--path=/var/lib/ethereum/beacon/beaconchaindata/beaconchain.db
--prefix=<string>

prefix of db record key to match against (eg 0xa1 would match 0xa10, 0xa1f etc)

Hex key prefix (with 0x) to match in the bucket. Without it the command does nothing.

--prefix=0xa1
--print-keys

only display keys, not values

Prints the matching keys. Printing values is not implemented, so a prefix scan fails unless this flag is set.

default false

prysmctl db buckets

list db buckets

--path=<string>

path to directory containing beaconchain.db

Accepted but not read: the command prints the bucket names compiled into this prysmctl version without opening any database.

prysmctl db slasher-span-display

visualise values in db span bucket

--db-path-directory=<string>

path to directory containing slasher.db

Directory that contains slasher.db (the slasher database of a beacon node running with --slasher). Required. Stop the beacon node first.

--validator-index=<uint64>

filter by validator index

Validator whose min or max spans are shown. Required.

default 0

--epoch=<uint64>

filter by epoch

Source epoch to show. The command displays the chunk containing this epoch. Required.

default 0

--chunk-kind=<string>

chunk kind to query (maxspan|minspan)

minspan or maxspan: which of the two surround-vote span arrays to read.

default minspan

--chunk-size=<uint64>

chunk size to query

Epochs per chunk. Must match the slasher parameters the database was written with; leave it unset to use the defaults.

default 16

--validator-chunk-size=<uint64>

validator chunk size to query

Validators per chunk. Must match the slasher parameters the database was written with; leave it unset to use the defaults.

default 256

--history-length=<uint64>

history length to query

Epochs of history the slasher keeps. Must match the slasher parameters the database was written with; leave it unset to use the defaults.

default 4096

--display-all-validators-in-chunk

display all validators in chunk

Shows a row for every validator stored in the same chunk, not only --validator-index.

default false

--display-all-epochs-in-chunk

display all epochs in chunk

Shows every epoch of the chunk as columns, not only --epoch.

default false

prysmctl p2p send beacon-blocks-by-range

Request a range of blocks from a beacon node via a p2p connection

--chain-config-file=<string>

Path to a YAML file with chain config values.

Chain config YAML for a custom network. Loaded after the network selection, so it overrides it.

--network=<string>

network to run on (mainnet, sepolia, holesky)

mainnet, sepolia, holesky or hoodi: sets fork digests and parameters so the handshake with the peer succeeds.

--network=hoodi

default mainnet

--peer-multiaddrs=<string>

comma-separated, peer multiaddr(s) to connect to for p2p requests

Peers to send the blocks-by-range request to, as comma-separated libp2p multiaddrs including the peer ID. Without it, the peers are read from the Prysm beacon node at --prysm-api-endpoints.

--peer-multiaddrs=/ip4/127.0.0.1/tcp/13000/p2p/<PEER_ID>
--client-port-tcp=<uint>

TCP port to use for the client as a libp2p host

Local TCP port of the temporary libp2p host. Change it if 13001 is in use.

default 13001

--client-port-quic=<uint>

QUIC port to use for the client as a libp2p host

Local QUIC (UDP) port of the temporary libp2p host.

default 13001

--prysm-api-endpoints=<string>

comma-separated, gRPC API endpoint(s) for Prysm beacon node(s)

gRPC endpoint(s) of Prysm beacon nodes. Always needed: the first one provides genesis and head information for the status handshake, and they supply peers when --peer-multiaddrs is not set.

--prysm-api-endpoints=127.0.0.1:4000

default localhost:4000

--start-slot=<uint64>

start slot for blocks by range request. If unset, will use start_slot(current_epoch-1)

First slot requested. 0 means the first slot of the previous epoch, taken from the beacon node head.

default 0

--count=<uint64>

number of blocks to request, (default 32)

Number of slots to request, starting at --start-slot.

default 32

--step=<uint64>

number of steps of blocks in the range request, (default 1)

Slot step of the request. Recent specs deprecate step and expect 1; other values are only useful for testing how peers respond.

default 1

prysmctl p2p send blobs-by-range

Request a range of blobs from a beacon node via a p2p connection

--chain-config-file=<string>

Path to a YAML file with chain config values.

Chain config YAML for a custom network. Loaded after the network selection, so it overrides it.

--peer-multiaddrs=<string>

comma-separated, peer multiaddr(s) to connect to for p2p requests

Peers to send the blob-sidecars-by-range request to, as comma-separated libp2p multiaddrs including the peer ID. Without it, the peers are read from the Prysm beacon node at --prysm-api-endpoints.

--peer-multiaddrs=/ip4/127.0.0.1/tcp/13000/p2p/<PEER_ID>
--client-port-tcp=<uint>

TCP port to use for the client as a libp2p host

Local TCP port of the temporary libp2p host. Change it if 13001 is in use.

default 13001

--client-port-quic=<uint>

QUIC port to use for the client as a libp2p host

Local QUIC (UDP) port of the temporary libp2p host.

default 13001

--prysm-api-endpoints=<string>

comma-separated, gRPC API endpoint(s) for Prysm beacon node(s)

gRPC endpoint(s) of Prysm beacon nodes. Always needed: the first one provides genesis and head information for the status handshake, and they supply peers when --peer-multiaddrs is not set.

--prysm-api-endpoints=127.0.0.1:4000

default localhost:4000

--start-slot=<uint64>

start slot for blobs by range request. If unset, will use start_slot(current_epoch-1)

First slot requested. 0 means the first slot of the previous epoch, taken from the beacon node head.

default 0

--count=<uint64>

number of blobs to request, (default 32)

Number of slots whose blob sidecars are requested.

This command has no --network flag and assumes mainnet unless you pass --chain-config-file. Since Fulu (PeerDAS), peers serve data columns instead of blob sidecars for new slots.

default 32

prysmctl testnet generate-genesis

Generate a beacon chain genesis state

--chain-config-file=<string>

The path to a YAML file with chain config values

Chain config YAML (consensus-specs config.yaml format) of the new network. Required in practice: the command stops with No chain config file was provided without it.

--deposit-json-file=<string>

Path to deposit_data.json file generated by the staking-deposit-cli tool for optionally specifying validators in genesis state

deposit_data-*.json from the deposit CLI. Its validators are placed in the genesis state instead of deterministically generated ones.

--num-validators=<uint64>

Number of validators to deterministically generate in the genesis state

Number of validators generated from the well-known interop keys (insecure, test only). The flag is required even with --deposit-json-file.

--num-validators=64

default 0

--genesis-time=<uint64>

Unix timestamp seconds used as the genesis time in the genesis state. If unset, defaults to now()

Genesis Unix timestamp in seconds. If unset, the timestamp of --geth-genesis-json-in is used, and failing that the current time.

default 0

--genesis-time-delay=<uint64>

Delay genesis time by N seconds

Seconds added to the genesis time, which gives you time to start the nodes before the chain begins.

--genesis-time-delay=120

default 0

--override-eth1data

Overrides Eth1Data with values from execution client. If unset, defaults to false

Sets the state's eth1_data from block 0 of the execution client at --execution-endpoint (with an empty deposit tree).

default false

--geth-genesis-json-in=<string>

Path to a "genesis.json" file, containing a json representation of Geth's core.Genesis

Execution genesis (genesis.json) to base the network on. Its fork times (Shanghai, Cancun, Prague, Osaka) are rewritten to match the chain config and genesis time. Post-merge forks require baseFeePerGas in the file.

--geth-genesis-json-out=<string>

Path to write generated "genesis.json" file, containing a json representation of Geth's core.Genesis

Where to write the resulting execution genesis.json. Initialize your execution client with this file so both layers agree on genesis.

--execution-endpoint=<string>

Endpoint to preferred execution client. If unset, defaults to Geth

Execution client JSON-RPC URL, used only with --override-eth1data.

default http://localhost:8545

--fork=<generic>

Name of the BeaconState schema to use in output encoding [phase0,altair,bellatrix,capella,deneb,electra,fulu]

Fork whose BeaconState layout the genesis uses, for example electra or fulu. It should match the fork active at epoch 0 in your chain config.

--fork=electra

default phase0

--output-ssz=<string>

Output filename of the SSZ marshaling of the generated genesis state

Output path for the SSZ-encoded state, the format beacon nodes load with --genesis-state. At least one output flag is required.

--output-ssz=genesis.ssz
--output-yaml=<string>

Output filename of the YAML marshaling of the generated genesis state

Output path for a YAML dump of the state, for inspection.

--output-json=<string>

Output filename of the JSON marshaling of the generated genesis state

Output path for a JSON dump of the state, for inspection.

prysmctl weak-subjectivity checkpoint

Compute the latest weak subjectivity checkpoint (block_root:epoch) using trusted server data.

--beacon-node-host=<string>

host:port for beacon node to query

Trusted beacon node REST API. Prysm nodes answer from their weak subjectivity endpoint; for other clients the checkpoint is computed from the head state. Prints a --weak-subjectivity-checkpoint=<root>:<epoch> value for the beacon node.

prysmctl weak-subjectivity checkpoint --beacon-node-host=http://127.0.0.1:3500

default http://localhost:3500

--http-timeout=<duration>

timeout for http requests made to beacon-node-url (uses duration format, ex: 2m31s). default: 2m

Timeout for each HTTP request. Raise it if the fallback path has to download a full state from a slow node.

default 2m0s

prysmctl validator withdraw

Assign Ethereum withdrawal addresses to validator keys. WARNING: once set values are included they can no longer be updated.

--beacon-node-host=<string>

host:port for beacon node to query

REST API of a synced beacon node that receives the signed messages, as host:port or a URL.

--beacon-node-host=http://127.0.0.1:3500

Read the guide

default 127.0.0.1:3500

--path=<string>

path to the signed withdrawal messages JSON

A JSON file, or a directory searched for .json files, containing signed BLS-to-execution changes (the bls_to_execution_change-*.json output of the deposit CLI). Files that are not such lists are skipped with a warning.

--path=./bls_to_execution_changes

Read the guide

--confirm

WARNING: User confirms and accepts responsibility of all input data provided and actions for setting their withdrawal address for their validator key. This action is not reversible and withdrawal addresses can not be changed once set.

Confirms that you checked the withdrawal addresses. Required together with --accept-terms-of-use; without both, the command prints a warning and stops.

Once included on chain, the withdrawal address cannot be changed. Check every address before you run this.

default false

--verify-only

overrides withdrawal command to only verify whether requests are in the pool and does not submit withdrawal requests

Does not submit anything: only checks whether the messages in --path are in the beacon node's operation pool. Messages already included in a block are no longer in the pool, so check a block explorer too.

Read the guide

default false

--config-file=<string>

Filepath to a yaml file with flag values.

YAML file with values for this command's flags (keys are flag names). Flags on the command line win.

--accept-terms-of-use

Accepts Terms and Conditions (for non-interactive environments).

Accepts the Prysm terms of use. This command requires it on every run, together with --confirm.

default false

prysmctl validator proposer-settings

Display or recreate currently used proposer settings.

--config-file=<string>

Filepath to a yaml file with flag values.

YAML file with values for this command's flags. Flags on the command line win.

--default-fee-recipient=<string>

default fee recipient used for proposer-settings, only used with --output-proposer-settings-path

Fee recipient written to default_config of the generated file. Only used with --output-proposer-settings-path; if omitted there, you are prompted for it.

Read the guide

--token=<string>

keymanager API bearer token, note: currently required but may be removed in the future, this is the same token as the web ui token.

The validator's Keymanager API token (contents of its --keymanager-token-file). Required.

Read the guide

--validator-host=<string>

host:port for validator client.

URL of the running validator's HTTP API (started with --rpc). Required: you must pass it even for the default http://127.0.0.1:7500.

--validator-host=http://127.0.0.1:7500

Read the guide

default http://127.0.0.1:7500

--output-proposer-settings-path=<string>

path to outputting a proposer settings file ( i.e. ./path/to/proposer-settings.json), file does not include builder settings and will need to be added for advanced users using those features

Writes the validator's current fee recipients as a proposer settings JSON file you can pass to --proposer-settings-file. Without it, the command only prints them. Gas limits and builder options are not exported.

--output-proposer-settings-path=./proposer-settings.json

Read the guide

prysmctl validator exit

Performs a voluntary exit on selected accounts

--wallet-dir=<altsrc.string>

Path to a wallet directory on-disk for Prysm validator accounts.

Prysm wallet holding the keys to exit. You must pass it explicitly (or use the Web3Signer flags); the default location is not assumed.

Read the guide

default ~/Library/Eth2Validators/prysm-wallet-v2

--wallet-password-file=<altsrc.string>

Path to a plain-text, .txt file containing your wallet password.

File with the wallet password, to skip the prompt. A trailing newline is ignored.

--account-password-file=<altsrc.string>

Path to a plain-text, .txt file containing a password for a validator account.

Accepted for compatibility; exits are signed with keys from the unlocked wallet, so only the wallet password is needed.

--public-keys=<altsrc.string>

Comma separated list of public key hex strings to specify on which validator accounts to perform a voluntary exit.

Validators to exit, as comma-separated hex public keys. Without it (and without --exit-all) you pick them interactively.

--public-keys=0x<PUBKEY>

Read the guide

--beacon-rpc-provider=<altsrc.string>

WARNING: The gRPC API will remain the default and fully supported through v8 (expected in 2026) but will be eventually removed in favor of REST API.. Beacon node RPC provider endpoint.

gRPC host:port of a synced beacon node (its --rpc-port, default 4000). The command refuses to run while that node is syncing.

--beacon-rpc-provider=127.0.0.1:4000

Read the guide

default 127.0.0.1:4000

--validators-external-signer-url=<altsrc.string>

URL for consensys' web3signer software to use with the Prysm validator client.

Signs the exits with Web3Signer instead of a local wallet. Pass it with --validators-external-signer-public-keys.

Read the guide

--validators-external-signer-public-keys=<altsrc.string list>

Comma separated list of public keys OR an external url endpoint for the validator to retrieve public keys from for usage with web3signer.

Web3Signer keys available for the exit: a comma-separated list or a public keys URL.

Read the guide

--grpc-max-msg-size=<altsrc.int>

WARNING: The gRPC API will remain the default and fully supported through v8 (expected in 2026) but will be eventually removed in favor of REST API.. Integer to define max receive message call size (in bytes). If serving a public gRPC server, set this to a more reasonable size to avoid resource exhaustion from large messages. Validators with as many as 10000 keys can be run with a max message size of less than 50Mb. The default here is set to a very high value for local users.

Maximum gRPC response size in bytes. The default is effectively unlimited.

default 2147483647

--tls-cert=<altsrc.string>

Certificate for secure gRPC. Pass this and the tls-key flag in order to use gRPC securely.

Certificate to verify the beacon node's gRPC TLS certificate, if it serves TLS.

--grpc-headers=<altsrc.string>

WARNING: The gRPC API will remain the default and fully supported through v8 (expected in 2026) but will be eventually removed in favor of REST API.. Comma separated list of key value pairs to pass as gRPC headers for all gRPC calls. Example: --grpc-headers=key=value

Extra key=value gRPC metadata, comma-separated, for example an auth header for a proxy.

--grpc-retries=<altsrc.uint>

WARNING: The gRPC API will remain the default and fully supported through v8 (expected in 2026) but will be eventually removed in favor of REST API.. Number of attempts to retry gRPC requests.

Retries for a failed gRPC call before giving up.

default 5

--grpc-retry-delay=<altsrc.duration>

WARNING: The gRPC API will remain the default and fully supported through v8 (expected in 2026) but will be eventually removed in favor of REST API.. Amount of time between gRPC retry requests.

Base delay between gRPC retries (linear backoff).

default 1s

--exit-all

Exits all validators. This will still require the staker to confirm a userprompt for the action.

Selects every key in the wallet or remote signer. You still have to confirm unless --force-exit is set.

Exits are irreversible. Check the printed key list before confirming.

default false

--force-exit

Exits without displaying the confirmation prompt.

Skips the final continue with the voluntary exit? (y/n) confirmation, for scripts.

Combined with --exit-all, this exits every key without any prompt.

default false

--exit-json-output-dir=<altsrc.string>

Output directory to write voluntary exits as individual unencrypted JSON files. If this flag is provided, voluntary exits will be written to the provided directory and will not be broadcasted.

Writes each signed exit to a JSON file in this directory instead of broadcasting it. Still needs a synced beacon node to sign.

A signed exit stays valid. Anyone who gets the file can broadcast it.

Read the guide

--mainnet

Runs on Ethereum main network. This is the default and can be omitted.

Signs the exit for mainnet (the default). Use the network your validators run on; only one network flag can be set.

default true

--sepolia

Runs Prysm configured for the Sepolia test network.

Signs the exit for Sepolia. Use the network your validators run on; only one network flag can be set.

default false

--holesky

Runs Prysm configured for the Holesky test network.

Signs the exit for Holesky (being retired). Use the network your validators run on; only one network flag can be set.

default false

--hoodi

Runs Prysm configured for the Hoodi test network.

Signs the exit for Hoodi. Use the network your validators run on; only one network flag can be set.

default false

--accept-terms-of-use

Accepts Terms and Conditions (for non-interactive environments).

Accepts the terms of use without the interactive prompt. Pass it in scripts and other non-interactive runs.

default false