Last update: February 9, 2022

Subcommands

This reference describes the syntax of the Hyperledger Besu Command Line Interface (CLI) subcommands.

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.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 will be imported.

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=rinkeby --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.

`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.

`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.

`operator`

Provides operator actions.

`generate-blockchain-config`

Syntax

besu operator generate-blockchain-config --config-file=<FILE> --to=<DIRECTORY> [--genesis-file-name=<FILE>] [--private-key-file-name=<FILE>] [--public-key-file-name=<FILE>]

Example

besu operator generate-blockchain-config --config-file=config.json --to=myNetworkFiles

Generates an IBFT 2.0 or QBFT genesis file.

The configuration file has two nested JSON nodes. The first is the genesis property defining the IBFT 2.0 or QBFT genesis file, except for the extraData string. The second is the blockchain property defining the number of key pairs to generate.

`generate-log-bloom-cache`

Syntax

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

Example

besu --network=goerli --data-path=/project/goerli 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.

`rlp`

Provides RLP related actions.

`encode`

Syntax

besu rlp encode [--from=<FILE>] [--to=<FILE>] [--type=<type>]

File example

besu rlp encode --from=ibft_extra_data.json --to=extra_data_for_ibft_genesis.txt --type=IBFT_EXTRA_DATA

Standard input/output example

cat extra_data.json | besu rlp encode > rlp.txt

Encodes the RLP hexadecimal string for use in a IBFT 2.0 or QBFT genesis file. The default type is IBFT_EXTRA_DATA.

Supported types are:

IBFT_EXTRA_DATA - The IBFT 2.0 genesis file includes the IBFT_EXTRA_DATA type in the extraData property.
QBFT_EXTRA_DATA - The QBFT genesis file includes the QBFT_EXTRA_DATA type in the extraData property.

IBFT 2.0 extra data

To generate the RLP encoded extraData string, specify a JSON input that is an array of validator addresses in ascending order.

JSON Schema for IBFT_EXTRA_DATA

Use the following JSON Schema to validate that your JSON data is well formed. To validate your JSON content, use an online validation tool, such as https://www.jsonschemavalidator.net/.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://org.hyperledger.besu/cli_rlp_ibft_extra_data.json",
  "type": "array",
  "definitions": {},
  "title": "IBFT extra data",
  "description":"JSON format used as input to generate an IBFT extra data RLP string",
  "items": {
    "$id": "#/address",
    "type": "string",
    "title": "Validator address",
    "description":"The validator node address",
    "default": "",
    "examples": [
      "be068f726a13c8d46c44be6ce9d275600e1735a4",
      "5ff6f4b66a46a2b2310a6f3a93aaddc0d9a1c193"
    ],
    "pattern":"^([0-9a-f]{40})$"
  }
}

Example IBFT_EXTRA_DATA encoding

JSON Input

[
  "be068f726a13c8d46c44be6ce9d275600e1735a4",
  "5ff6f4b66a46a2b2310a6f3a93aaddc0d9a1c193"
]

RLP Output

0xf853a00000000000000000000000000000000000000000000000000000000000000000ea94be068f726a13c8d46c44be6ce9d275600e1735a4945ff6f4b66a46a2b2310a6f3a93aaddc0d9a1c193808400000000c0

`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:

`validate-config`

Syntax

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

Example

besu validate-config --config-file ../besu-local-nodes/config/besu/besu1.conf

Performs basic syntax validation of the specified TOML 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).

Subcommands

blocks

import

export

public-key

export

export-address

password

hash

operator

generate-blockchain-config

generate-log-bloom-cache

rlp

encode

retesteth

validate-config

`blocks`

`import`

`export`

`public-key`

`export`

`export-address`

`password`

`hash`

`operator`

`generate-blockchain-config`

`generate-log-bloom-cache`

`rlp`

`encode`

`retesteth`

`validate-config`