Subcommands

This reference describes the syntax of the Besu command line interface (CLI) subcommands.

note

This reference contains subcommands that apply to both public and private networks. For private-network-specific subcommands, see the private network subcommands reference.

To start a Besu node using subcommands, run:

besu [OPTIONS] [SUBCOMMAND] [SUBCOMMAND OPTIONS]

If using Bash or Z shell, you can view subcommand suggestions by pressing the Tab key twice.

besu Tab+Tab

blocks

Provides blocks related actions.

import

Syntax

besu blocks import [--skip-pow-validation-enabled] [--start-block=<LONG>] [--end-block=<LONG>] --from=<block-file>

Example

besu blocks import --skip-pow-validation-enabled --start-block=100 --end-block=300 --from=/home/me/me_project/mainnet-export1.blocks --from=/home/me/me_project/mainnet-export2.blocks

Imports a block or range of blocks from the specified file into the blockchain database.

You can specify the starting index of the block range to import with --start-block. If omitted, the default start block is 0 (the beginning of the chain).

You can specify the ending index (exclusive) of the block range to import with --end-block. If omitted, all blocks after the start block are imported.

You can specify multiple --from arguments. This can be useful when blocks have been exported over time to multiple files. If multiple files are provided they are read in the order specified in the command.

Including --skip-pow-validation-enabled skips validation of the mixHash when importing blocks.

note

Use --skip-pow-validation-enabled when performing Ethereum Foundation hive testing.

export

Syntax

besu blocks export [--start-block=<LONG>] [--end-block=<LONG>] --to=<block-file>

Example

besu --network=holesky --data-path=/home/data/ blocks export --start-block=100 --end-block=300 --to=/home/exportblock.bin

Exports a block or range of blocks from storage to a file in RLP format.

If you omit --start-block, the default start block is 0 (the beginning of the chain), and if you omit --end-block, the default end block is the current chain head.

If you are not running the command against the default network (Mainnet), specify the --network or --genesis-file parameter.

operator

Provides operator actions.

generate-log-bloom-cache

Syntax

besu operator generate-log-bloom-cache [--start-block=<BLOCK_NUMBER>] [--end-block=<BLOCK_NUMBER>]

Example

besu --network=holesky --data-path=/project/holesky operator generate-log-bloom-cache --start-block=0 --end-block=100000

tip

Manually executing generate-log-bloom-cache is not required unless you set the --auto-log-bloom-caching-enabled command line option to false.

Generates cached log bloom indexes for blocks. APIs use the cached indexes for improved log query performance.

note

Each index file contains 100000 blocks. The last fragment of blocks less that 100000 are not indexed.

To generate cached log bloom indexes while the node is running, use the admin_generateLogBloomCache API.

password

Provides password related actions.

hash

Syntax

besu password hash --password=<my-password>

Example

besu password hash --password=myPassword123

Generates the hash of a given password. Include the hash in the credentials file for JSON-RPC API authentication.

public-key

Provides node public key related actions.

caution

To get the public key or address of a node, ensure you use the --data-path or --node-private-key-file option with the public-key command. Otherwise, a new node key is silently generated when starting Besu.

export

Syntax

besu public-key export [--node-private-key-file=<file>] [--to=<key-file>] [--ec-curve=<ec-curve-name>]

Example (to standard output)

besu --data-path=<node data path> public-key export --node-private-key-file=/home/me/me_node/myPrivateKey --ec-curve=secp256k1

Example (to file)

besu --data-path=<node data path> public-key export --node-private-key-file=/home/me/me_node/myPrivateKey --to=/home/me/me_project/not_precious_pub_key --ec-curve=secp256k1

Outputs the node public key to standard output or to the file specified by --to=<key-file>. You can output the public key associated with a specific private key file using the --node-private-key-file option. The default elliptic curve used for the key is secp256k1. Use the --ec-curve option to choose between secp256k1 or secp256r1.

export-address

Syntax

besu public-key export-address [--node-private-key-file=<file>] [--to=<address-file>] [--ec-curve=<ec-curve-name>]

Example (to standard output)

besu --data-path=<node data path> public-key export-address --node-private-key-file=/home/me/me_node/myPrivateKey --ec-curve=secp256k1

Example (to file)

besu --data-path=<node data path> public-key export-address --node-private-key-file=/home/me/me_node/myPrivateKey --to=/home/me/me_project/me_node_address --ec-curve=secp256k1

Outputs the node address to standard output or to the file specified by --to=<address-file>. You can output the address associated with a specific private key file using the --node-private-key-file option. The default elliptic curve used for the key is secp256k1. Use the --ec-curve option to choose between secp256k1 or secp256r1.

retesteth

Syntax

besu retesteth [--data-path=<PATH>] [--rpc-http-host=<HOST>] [--rpc-http-port=<PORT>] [-l=<LOG VERBOSITY LEVEL>] [--host-allowlist=<hostname>[,<hostname>…]… or * or all]

Example

besu retesteth --data-path=/home/me/me_node --rpc-http-port=8590 --host-allowlist=*

Runs a Retesteth-compatible server. Retesteth is a developer tool that can generate and run consensus tests against any Ethereum client running such a server.

The command accepts the following command line options:

• --data-path
• --host-allowlist
• --rpc-http-host
• --rpc-http-port
• --logging

storage

Provides storage related actions.

revert-metadata

Syntax

besu storage revert-metadata v2-to-v1

Reverts the modifications made by the database metadata refactor. If you need to downgrade Besu, run this subcommand before installing the previous binaries.

revert-variables

Syntax

besu --config-file <PATH-TO-CONFIG-FILE> storage revert-variables

Example

besu --config-file config.toml storage revert-variables

Reverts the modifications made by the variables storage feature. If you need to downgrade Besu, first run this subcommand specifying the path to the configuration file normally used to start Besu.

rocksdb usage

Syntax

besu --config-file <PATH-TO-CONFIG-FILE> storage rocksdb usage

Example

besu --config-file config.toml storage rocksdb usage

Example output

|--------------------------------|-----------------|-------------|-----------------|------------------|
| Column Family                  | Keys            | Total Size  | SST Files Size  | Blob Files Size  |
|--------------------------------|-----------------|-------------|-----------------|------------------|
| BLOCKCHAIN                     | 2355141414      | 933 GiB     | 166 GiB         | 767 GiB          |
| VARIABLES                      | 26              | 240 KiB     | 240 KiB         | 0 B              |
| ACCOUNT_INFO_STATE             | 9634454         | 496 MiB     | 496 MiB         | 0 B              |
| ACCOUNT_STORAGE_STORAGE        | 24041432        | 1 GiB       | 1 GiB           | 0 B              |
| CODE_STORAGE                   | 37703864        | 12 GiB      | 12 GiB          | 0 B              |
| TRIE_BRANCH_STORAGE            | 1885032116      | 138 GiB     | 138 GiB         | 0 B              |
| TRIE_LOG_STORAGE               | 267301          | 17 GiB      | 17 GiB          | 0 B              |
|--------------------------------|-----------------|-------------|-----------------|------------------|
| ESTIMATED TOTAL                | 4311820607      | 1104 GiB    | 337 GiB         | 767 GiB          |
|--------------------------------|-----------------|-------------|-----------------|------------------|

Displays the disk space used by the RocksDB key-value database, categorized into column families.

trie-log

Provides actions related to managing, recording, and logging changes for the Bonsai Trie data.

count

Syntax

besu --config-file <PATH-TO-CONFIG-FILE> storage trie-log count

Example

besu --config-file config.toml storage trie-log count

Example output

trieLog count: 742311
 - canonical count: 681039
 - fork count: 217
 - orphaned count: 61055

Displays the number of trie logs in the database. This is the number of keys for the TRIE_LOG_STORAGE column family in RocksDB. The following are specified in the trieLog count:

• canonical count represents the finalized blockchain.
• fork count represents non-finalized branches of the blockchain.
• orphaned count represents trie logs not in the blockchain, which can occur during block creation.

prune

Syntax

besu --config-file <PATH-TO-CONFIG-FILE> storage trie-log prune

Example

besu --config-file config.toml storage trie-log prune

Example setting retention limit

besu --config-file config.toml --bonsai-historical-block-limit=1024 storage trie-log prune

Removes all trie log layers below the specified retention limit, including orphaned trie logs. You can configure the retention limit using --bonsai-historical-block-limit. The retention limit should match the configuration used with --bonsai-limit-trie-logs-enabled. The default limit is 512.

validate-config

Syntax

besu validate-config --config-file <PATH-TO-CONFIG-FILE>

Example

besu validate-config --config-file config.toml

Performs basic syntax validation of the specified configuration file. Checks TOML syntax (for example, valid format and unmatched quotes) and flags unknown options. Doesn't check data types, and doesn't check dependencies between options (this is done at Besu startup).