Etherstats - Install And User Guide



What are Ethstats, you may ask?


Ethereum Network Stats. This is a visual interface for tracking ethereum network status. It uses WebSockets to receive stats from running nodes and output them through an angular interface. It is the front-end implementation for eth-net-intelligence-api.
What do the stats mean?

Last Block

This is the last block that was mined. On ethstats, it shows the time since something was mined.

A block is a collection of transactions. At time of writing, the last block is 3716787

Gas Limits

Gas is a measure of computational effort. It is the internal pricing for running a transaction or contract in Ethereum.

The gas system is not very different from the use of Kw for measuring electricity home use. One difference from actual energy market is that the originator of the transaction sets the price of gas, to which the miner can or not accept, this causes an emergence of a market around gas.

Best Block

This is a valid block with a chain that has the highest sum of work.


Difficulty is a measure of how difficult it is to find a hash below a given target. The difficulty dynamically adjusts so that on average one block is produced by the entire network every 12 seconds.


Getting started


Please make sure you have the following installed and running properly

  • Node.js >= 8.11
  • NPM >= 5.6 (Usually NPM is distributed with Node.js)
  • Build Tools - To compile and install native addons from NPM you may also need to install tools like: make, gcc, g++. E.q. on ubuntu build-essential package has all the necessary tools.
  • Yarn >= 1.5 Yarn is optional, being an alternative to NPM.
  • Git - Some dependencies are downloaded through Git.
  • Geth or Parity running in one of the supported configurations synced on the Ethereum main/foundation chain
  • JSON-RPC http or websockets or ipc APIs enabled and accessible on the Ethereum node of choice (Geth/Parity)

Supported node configurations


  • fast (--syncmode "fast")
  • full (--syncmode "full")
  • light (--syncmode "light")

tested 1.8.1,


  • fast (--pruning fast)
  • archive (--pruning archive)
  • with no ancient blocks (--no-ancient-blocks)

tested 1.7.11, 1.8.6, 1.8.7, 1.9.0, 1.9.1, 1.9.2, 1.10.0,


Install ethstats-cli globally

With npm:

npm install -g ethstats-cli

If you encounter permissions issues at install time please see troubleshooting section: NPM global package permissions problem

Or yarn:

yarn global add ethstats-cli

If after installing the package with yarn, the binaries are not found please see troubleshooting section: Binaries not found


Update ethstats-cli to the latest available version

With npm:

npm install -g ethstats-cli@latest

Or yarn:

yarn global upgrade ethstats-cli


On the first run of the app you will be asked a series of questions to setup your node. Either follow the on screen instructions or see CLI options for a non-interactive mode.

The app is configured by default to connect to an Ethereum node on the local machine (http://localhost:8545) that is running on the mainnet network. To connect to a node running on another host see --client-url under CLI options.

After the setup is done, your node will be visible on

IMPORTANT: To be able to extract all statistics from the Ethereum node we recommend running the app on the same host. The usage information about the node like cpu and memory load cannot be extracted if on a different host.


To run the app in interactive mode you can use the following command:

$ ethstats-cli

CLI options:

  --help, -h                Show help
  --version, -V             Show version
  --debug, -d               Output values sent to server
  --verbose, -v             Output more detailed information
  --server-url              Server URL (Must include protocol and port if any)
  --net, -n                 Specify Ethereum network your node is running on (Default: mainnet)
                            If --server-url is specified, this option is ignored
  --client-url              Client URL (Must include protocol and port if any; Default: http://localhost:8545)
                            Based on the protocol specified in the url (http | ws) the app sets the corresponding  Web3 provider
                            If --client-ipc-path is specified, this option is ignored
  --client-ipc-path         Client IPC path
  --configurator-url        Configurator URL (Must include protocol and port if any). Custom configuration service to provide application specific configs.
  --register, -r            Register node in non-interactive mode
    --account-email         Account identification, also used in case of node/secret-key recovery
                            It is possible to have multiple nodes under the same account-email
    --node-name             Name of the node. 
If node is already registered, a unique 5 character hash will be appended

Running the app in non-interactive mode for the first time, you'll need to specify the --register option together with --account-email and --node-name. Like this no questions will be asked. All other CLI options have default values.


$ ethstats-cli --register --account-email --node-name your_node_name

If the app is already registered and you still specify the registration CLI option like in the example command above, they will be avoided.

If the node was successfully registered, a configuration file is created to persist the values of the CLI options previously specified. Every CLI option that passes a value, once specified, it's value is stored in this configuration file, so the next time the app is started there's no need to specify does CLI options again.


To keep the app running at all times, you can run it as a daemon using the following command:

$ ethstats-daemon

Daemon options:

  start               Start daemon
  stop                Stop daemon
  restart             Restart daemon. If it is already started, the process will be stopped first.
  status              Show infos about the daemon.
  kill                Ethstats daemon uses PM2 as a process manager. This command will kill PM2 god daemon.

If any CLI options are specified after the Daemon option, they will be forwarded to the forked process. The Daemon mode is implemented programmatically through the PM2 API. The API does not support the "startup" feature. To handle start on boot, check out the PM2 instructions.

With PM2

For more control you can use directly PM2. Here is a JSON format process file that we recommend:

  "apps": [{
    "name": "ethstats-cli",
    "script": "ethstats-cli",
    "pid": "~/.ethstats-cli/",
    "error": "~/.ethstats-cli/ethstats-cli.log",
    "output": "~/.ethstats-cli/ethstats-cli.log",
    "args": "--verbose",
    "restartDelay": 1000

To handle daemon start at boot time, please visit PM2-Startup.

In Docker

Installing and running

The following commands assume that the Ethereum node is either running locally or in docker with --net host. For other options you should check out CLI options.

Make a directory where your configuration files will be persisted.

mkdir /opt/ethstats-cli

Then run the following command to run from alethio/ethstats-cli docker image:

docker run -d \
--restart always \
--net host \
-v /opt/ethstats-cli/:/root/.config/configstore/ \
alethio/ethstats-cli --register --account-email --node-name your_node_name

or from node:latest docker image:

docker \
run -d \
--name ethstats-cli \
--restart always \
--net host \
-v /opt/ethstats-cli/:/root/.config/configstore/ \
node:latest \
/bin/sh -c "yarn global add ethstats-cli && ethstats-cli --register --account-email --node-name your_node_name"

The docker commands are run with -d, that means ethstats-cli is started in non-interactive mode.

To run in interactive mode change -d to -it and remove the --register option along with --account-email and --node-name.

If you already had a configuration file, the settings from that file will be used and the command line ignored. Delete the files in /opt/ethstats-cli to add a node with different settings.


If you started from alethio/ehtstats-cli docker image:

docker pull alethio/ethstats-cli
docker stop ethstats-cli && docker rm ethstats-cli

then run it again.

If you started from node/latest docker image, just stop and remove the ethstats-cli:

docker stop ethstats-cli && docker rm ethstats-cli

then run it again.


NPM global package permissions problem

We recommend installing NPM global packages without sudo. If you encountered issues when tried to install ethstats-cli as a global package with or without sudo regarding permissions, we recommend using this script npm-global-no-sudo to fix the issue.

Binaries not found

If you installed ethstats-cli as a global package with Yarn and the binaries are not found, we recommend running the following command:

export PATH="$PATH:`yarn global bin`" && echo
0 out of 0 found this helpful



Please sign in to leave a comment.