Skip to main content

Basic Usage

Erigon is mainly operated through the command line. The commands may vary based on your installation method.

Open your terminal and simply start Erigon with the command:

erigon [options]

To gracefully stop Erigon simply press CTRL + C.

All-in-One Client​

The all-in-one client is the preferred option for most users:

./build/bin/erigon [options]

This CLI command allows you to run an Ethereum full node where every process is integrated and no special configuration is needed.

The default Consensus Layer utilized is Caplin, the Erigon flagship embedded CL.

Example of configuration​

To run Erigon with RPC Daemon, TxPool, and other components in a single process is the simplest way to get started. For better performance and load management, you might consider distributing these components across multiple machines.

./build/bin/erigon --datadir=/desired/path/to/datadir \
 --chain=mainnet \
 --port=30304 \
 --http.port=8546 \
 --torrent.port=42068 \
 --private.api.addr=127.0.0.1:9091 \
 --http \
 --ws \
 --http.api=eth,debug,net,trace,web3,erigon \
 --log.dir.path=/desired/path/to/logs \
 --torrent.download.rate=512mb

Flags of Interest​

  • Default data directory is /home/usr/.local/share/erigon. If you want to store Erigon files in a non-default location, use the flag:

    --datadir=/desired/path/to/datadir

  • The --chain=mainnet flag is set by default for Erigon to sync with the Ethereum mainnet. To explore other network options, check the Supported Networks section. For quick testing, consider selecting a testnet.

  • --log.dir.path dictates where logs will be output - useful for sending reports to the Erigon team when issues occur.

  • Based on the prune mode you want to run you can add --prune.mode=archive to run an archive node, --prune.mode=full for a full node (default value) or --prune.mode=minimal for a minimal node.

  • --http.addr=0.0.0.0 --http.api=eth,web3,net,debug,trace,txpool to use RPC Service and e.g. be able to connect your wallet.

  • --torrent.download.rate sets the torrent download rate cap. The default is 512mb (megabytes per second). During initial sync Erigon will use the full allowance — on a dedicated machine this is fine, but if you share the machine with other work you may want to lower it (e.g. --torrent.download.rate=128mb). Set --torrent.download.rate=Inf to remove the limit entirely.

To stop the Erigon node you can use the CTRL+C command.

Additional flags can be added to configure the node with several options.

How do I know it's syncing?​

Once your node is running, there are two ways to confirm it is making progress and to see exactly which stage of the initial sync it is in.

1. Read the live log line​

Erigon's logs are organized by staged sync. Every log line emitted by the sync engine is prefixed with the current stage and its position in the pipeline. For example:

INFO[02-20|15:00:00.123] [4/8 Bodies] Downloading block bodies   block=18234567 ...

The prefix [4/8 Bodies] means: "stage 4 of 8, currently in the Bodies stage". As stages complete, the prefix advances ([5/8 Senders], [6/8 Execution], …) until you reach [8/8 Finish], at which point the node is at the chain tip.

The full ordered stage list is in Logs → Stage Definitions.

2. Query the JSON-RPC​

If the RPC Daemon is enabled (default port 8545), the standard eth_syncing method tells you whether the node is still catching up and how far behind it is:

curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545
  • While syncing, the result is an object with currentBlock, highestBlock, and a stages array (one entry per stage, with {stage_name, block_number}). Subtract currentBlock from highestBlock to see how many blocks remain; the stages array gives you the same per-stage progress as the log prefix above. (startingBlock is also returned but is hardcoded to "0x0" and carries no meaningful info.)
  • Once fully synced, the result is simply false.
tip

For a quick reference on monitoring sync progress (including using AI assistants via MCP), see the Frequently Asked Questions.

Help​

To learn about the available commands, open your terminal in your Erigon 3 installation directory and run:

make help

This command will display a list of convenience commands available in the Makefile, along with their descriptions.

 go-version:                        print and verify go version
 validate_docker_build_args:        ensure docker build args are valid
 docker:                            validate, update submodules and build with docker
 setup_xdg_data_home:               TODO
 docker-compose:                    validate build args, setup xdg data home, and run docker-compose up
 dbg                                debug build allows see C stack traces, run it with GOTRACEBACK=crash. You don't need debug build for C pit for profiling. To profile C code use SETCGOTRCKEBACK=1
 erigon:                            build erigon
 all:                               run erigon with all commands
 db-tools:                          build db tools
 test:                              run unit tests with a 100s timeout
 test-integration:                  run integration tests with a 30m timeout
 lint-deps:                         install lint dependencies
 lintci:                            run golangci-lint linters
 lint:                              run all linters
 clean:                             cleans the go cache, build dir, libmdbx db dir
 devtools:                          installs dev tools (and checks for npm installation etc.)
 mocks:                             generate test mocks
 mocks-clean:                       cleans all generated test mocks
 solc:                              generate all solidity contracts
 abigen:                            generate abis using abigen
 gencodec:                          generate marshalling code using gencodec
 graphql:                           generate graphql code
 gen:                               generate all auto-generated code in the codebase
 bindings:                          generate test contracts and core contracts
 prometheus:                        run prometheus and grafana with docker-compose
 escape:                            run escape path={path} to check for memory leaks e.g. run escape path=cmd/erigon
 git-submodules:                    update git submodules
 install:                           copies binaries and libraries to DIST
 user_linux:                        create "erigon" user (Linux)
 user_macos:                        create "erigon" user (MacOS)
 hive:                              run hive test suite locally using docker e.g. OUTPUT_DIR=~/results/hive SIM=ethereum/engine make hive
 automated-tests                    run automated tests (BUILD_ERIGON=0 to prevent erigon build with local image tag)
 help:                              print commands help

For example, from your Erigon 3 installation directory, run:

make clean

This will execute the clean target in the Makefile, which cleans the go cache, build directory, and libmdbx db directory.