Skip to content

Pantheon Command Line

Breaking Changes in v0.9

In v0.9, the command line changed to improve usability. These are breaking changes; that is, in many cases the v0.8 command line options no longer work. This reference and the rest of the documentation has been updated to reflect these changes. The release notes include a mapping of the previous command line options to the new options.

This reference describes the syntax of the Pantheon Command Line Interface (CLI) options and subcommands.

pantheon [OPTIONS] [COMMAND]

Runs the Pantheon Ethereum full node client.

Tip

Use a configuration file to save the command line options in a file.

Options

banned-node-ids

--banned-node-ids=<bannedNodeId>[,<bannedNodeId>...]...
--banned-nodeids=0xc35c3...d615f,0xf42c13...fc456
banned-nodeids=["0xc35c3...d615f","0xf42c13...fc456"]

List of node IDs with which this node will not peer. The node ID is the public key of the node. You can specify the banned node IDs with or without the 0x prefix.

Tip

The singular --banned-node-id and plural --banned-node-ids are available and are just two names for the same option.

bootnodes

--bootnodes[=<enode://[email protected]:port>[,<enode://[email protected]:port>...]...]
--bootnodes=enode://[email protected]:30303,enode://[email protected]:30303
bootnodes=["enode://[email protected]:30303","enode://[email protected]:30303"]
--bootnodes

List of comma-separated enode URLs for P2P discovery bootstrap.

When connecting to MainNet or public testnets, the default is a predefined list of enode URLs.

On custom networks defined by --genesis-file option, an empty list of bootnodes is defined by default unless you define custom bootnodes as described in private network documentation.

Note

Specifying that a node is a bootnode must be done on the command line using --bootnodes option without value, not in a configuration file.

config-file

--config-file=<FILE>
--config-file=/home/me/me_node/config.toml

The path to the TOML configuration file. The default is none.

Note

This option is not used when running Pantheon from the Docker image or in a configuration file.

data-path

--data-path=<PATH>
--data-path=/home/me/me_node
data-path="/home/me/me_node"

The path to the Pantheon data directory. The default is the /build/distributions/pantheon-<version> directory in the Pantheon installation directory.

Note

This option is not used when running Pantheon from the Docker image.

discovery-enabled

--discovery-enabled=false
discovery-enabled=false

Enables or disables P2P peer discovery. The default is true.

genesis-file

Genesis file is used to create a custom network.

Tip

To use a public Ethereum network such as Rinkeby, use the --network option. The network option defines the genesis file for public networks.

--genesis-file=<FILE>
--genesis-file=/home/me/me_node/customGenesisFile.json
genesis-file="/home/me/me_node/customGenesisFile.json"

The path to the genesis file.

Important

The --genesis-file and --network option can’t be used at the same time.

Note

This option is not used when running Pantheon from the Docker image.

host-whitelist

--host-whitelist=<hostname>[,<hostname>...]... or * or all
--host-whitelist=medomain.com,meotherdomain.com
host-whitelist=["medomain.com", "meotherdomain.com"]

Comma-separated list of hostnames to allow access to the HTTP JSON-RPC API. Default is localhost.

Tip

To allow all hostnames, use * or all. We don’t recommend allowing all hostnames for production code.

max-peers

--max-peers=<INTEGER>
--max-peers=42
max-peers=42

Specifies the maximum P2P peer connections that can be established. The default is 25.

metrics-enabled

--metrics-enabled
metrics-enabled=true

Set to true to enable the metrics exporter. The default is false.

--metrics-enabled cannot be specified with --metrics-push-enabled. That is, either Prometheus polling or Prometheus push gateway support can be enabled but not both at once.

metrics-host

--metrics-host=<HOST>
--metrics-host=127.0.0.1
metrics-host="127.0.0.1"

Specifies the host on which Prometheus accesses Pantheon metrics. The metrics server respects the --host-whitelist option.

The default is 127.0.0.1.

metrics-port

--metrics-port=<PORT>
--metrics-port=6174
metrics-port="6174"

Specifies the port on which Prometheus accesses Pantheon metrics. The default is 9545.

metrics-push-enabled

--metrics-push-enabled[=<true|false>]
--metrics-push-enabled
metrics-push-enabled="true"

Set to true to start the push gateway integration.

--metrics-push-enabled cannot be specified with --metrics-enabled. That is, either Prometheus polling or Prometheus push gateway support can be enabled but not both at once.

metrics-push-host

--metrics-push-host=<HOST>
--metrics-push-host=127.0.0.1
metrics-push-host="127.0.0.1"

Host of the Prometheus Push Gateway. The default is 127.0.0.1. The metrics server respects the --host-whitelist option.

Note

When pushing metrics, ensure --metrics-push-host is set to the machine on which the push gateway is. Generally, this will be a different machine to the machine on which Pantheon is running.

metrics-push-interval

--metrics-push-interval=<INTEGER>
--metrics-push-interval=30
metrics-push-interval=30

Interval in seconds to push metrics when in push mode. The default is 15.

metrics-push-port

--metrics-push-port=<PORT>
--metrics-push-port=6174
metrics-push-port="6174"

Port of the Prometheus Push Gateway. The default is 9001.

metrics-push-prometheus-job

--metrics-prometheus-job=<metricsPrometheusJob>
--metrics-prometheus-job="my-custom-job"
metrics-prometheus-job="my-custom-job"

Job name when in push mode. The default is pantheon-client.

miner-coinbase

--miner-coinbase=<Ethereum account address>
--miner-coinbase=fe3b557e8fb62b89f4916b721be55ceb828dbd73
--miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"

Account to which mining rewards are paid. You must specify a valid coinbase when you enable mining using the --miner-enabled option or the miner_start JSON RPC-API method.

Note

This option is ignored in networks using Clique and IBFT 2.0 consensus protocols.

miner-enabled

--miner-enabled
miner-enabled=true

Enables mining when the node is started. Default is false.

miner-extra-data

--miner-extra-data=<Extra data>
--miner-extra-data=0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021
miner-extra-data="0x444F4E27542050414E4943202120484F444C2C20484F444C2C20484F444C2021"

A hex string representing the 32 bytes to be included in the extra data field of a mined block. The default is 0x.

min-gas-price

--min-gas-price=<minTransactionGasPrice>
--min-gas-price=1337
min-gas-price="1337"

The minimum price that a transaction offers for it to be included in a mined block. The default is 1000.

network

--network=<NETWORK>
--network=rinkeby
network="rinkeby"

Predefined network configuration. The default is mainnet.

Possible values are :

mainnet
Main Ethereum network
ropsten
PoW test network similar to current main Ethereum network.
rinkeby
PoA test network using Clique.
goerli
PoA test network using Clique.
dev
PoW development network with a very low difficulty to enable local CPU mining.

Note

Values are case insensitive, so either mainnet or MAINNET works.

Important

The --network and --genesis-file option cannot be used at the same time.

network-id

--network-id=<INTEGER>
--network-id=8675309
network-id="8675309"

P2P network identifier.

This option can be used to override the default network ID. The default value is the network chain ID defined in the genesis file.

node-private-key-file

--node-private-key-file=<FILE>
--node-private-key-file=/home/me/me_node/myPrivateKey
node-private-key-file="/home/me/me_node/myPrivateKey"

<FILE> is the path of the private key file of the node. The default is the key file in the data directory. If no key file exists, a key file containing the generated private key is created; otherwise, the existing key file specifies the node private key.

Attention

The private key is not encrypted.

Note

This option is not used when running Pantheon from the Docker image.

p2p-enabled

--p2p-enabled=<true|false>
--p2p-enabled=false
p2p-enabled=false

Enables or disables all p2p communication. The default is true.

p2p-host

--p2p-host=<HOST>
# to listen on all interfaces
--p2p-host=0.0.0.0
p2p-host="0.0.0.0"

Specifies the host on which P2P peer discovery listens. The default is 127.0.0.1.

Note

This option is not used when running Pantheon from the Docker image.

p2p-port

--p2p-port=<PORT>
# to listen on port 1789
--p2p-port=1789
p2p-port="1789"

Specifies the port on which P2P peer discovery listens. The default is 30303.

Note

This option is not used when running Pantheon from the Docker image.

privacy-enabled

--privacy-enabled[=<true|false>]
--privacy-enabled=false
privacy-enabled=false

Set to enable private transactions. The default is false.

Note

Privacy is under development and will be available in v1.1.

privacy-precompiled-address

--privacy-precompiled-address=<privacyPrecompiledAddress>

Address to which the privacy pre-compiled contract is mapped. The default is 126.

Note

Privacy is under development and will be available in v1.1.

privacy-public-key-file

--privacy-public-key-file=<privacyPublicKeyFile>

Path to the public key for the enclave.

Note

Privacy is under development and will be available in v1.1.

privacy-url

--privacy-url=<privacyUrl>

URL on which enclave is running.

Note

Privacy is under development and will be available in v1.1.

permissions-accounts-enabled

--permissions-accounts-enabled[=<true|false>]
--permissions-accounts-enabled
permissions-accounts-enabled=true

Set to enable account level permissions. The default is false.

Note

Permissions is under development and will be available in v1.0.

permissions-nodes-enabled

--permissions-nodes-enabled[=<true|false>]
--permissions-nodes-enabled
permissions-nodes-enabled=true

Set to enable node level permissions. The default is false.

Note

Permissions is under development and will be available in v1.0.

rpc-http-enabled

--rpc-http-enabled
rpc-http-enabled=true

Set to true to enable the HTTP JSON-RPC service. The default is false.

rpc-http-host

--rpc-http-host=<HOST>
# to listen on all interfaces
--rpc-http-host=0.0.0.0
rpc-http-host="0.0.0.0"

Specifies the host on which HTTP JSON-RPC listens. The default is 127.0.0.1.

To allow remote connections, set to 0.0.0.0

Caution

Setting the host to 0.0.0.0 exposes the RPC connection on your node to any remote connection. In a production environment, ensure you are using a firewall to avoid exposing your node to the internet.

Note

This option is not used when running Pantheon from the Docker image.

rpc-http-port

--rpc-http-port=<PORT>
# to listen on port 3435
--rpc-http-port=3435
rpc-http-port="3435"

Specifies the port on which HTTP JSON-RPC listens. The default is 8545.

Note

This option is not used when running Pantheon from the Docker image.

rpc-http-api

--rpc-http-api=<api name>[,<api name>...]...
--rpc-http-api=ETH,NET,WEB3
rpc-http-api=["ETH","NET","WEB3"]

Comma-separated APIs to enable on the HTTP JSON-RPC channel. When you use this option, the --rpc-http-enabled option must also be specified. The available API options are: ADMIN, ETH, NET, WEB3, CLIQUE, IBFT, DEBUG, and MINER. The default is: ETH, NET, WEB3.

Note

IBFT 2.0 is under development and will be available in v1.0.

Tip

The singular --rpc-http-api and plural --rpc-http-apis are available and are just two names for the same option.

rpc-http-cors-origins

--rpc-http-cors-origins=<url>[,<url>...]... or all or *
# You can whitelist one or more domains with a comma-separated list.

--rpc-http-cors-origins="http://medomain.com","https://meotherdomain.com"
rpc-http-cors-origins=["http://medomain.com","https://meotherdomain.com"]
# The following allows Remix to interact with your Pantheon node.

--rpc-http-cors-origins="http://remix.ethereum.org"

Specifies domain URLs for CORS validation. Domain URLs must be enclosed in double quotes and comma-separated.

Listed domains can access the node using JSON-RPC. If your client interacts with Pantheon using a browser app (such as Remix or a block explorer), you must whitelist the client domains.

The default value is "none". If you don’t whitelist any domains, browser apps cannot interact with your Pantheon node.

Note

To run a local Pantheon node as a backend for MetaMask and use MetaMask anywhere, set --rpc-http-cors-origins to "all" or "*". To allow a specific domain to use MetaMask with the Pantheon node, set --rpc-http-cors-origins to the client domain.

Tip

For development purposes, you can use "all" or "*" to accept requests from any domain, but we don’t recommend this for production code.

rpc-ws-enabled

--rpc-ws-enabled
rpc-ws-enabled=true

Set to true to enable the WebSockets JSON-RPC service. The default is false.

rpc-ws-api

--rpc-ws-api=<api name>[,<api name>...]...
--rpc-ws-api=ETH,NET,WEB3
rpc-ws-api=["ETH","NET","WEB3"]

Comma-separated APIs to enable on Websockets channel. When you use this option, the --rpc-ws-enabled option must also be specified. The available API options are: ETH, NET, WEB3, CLIQUE, IBFT, DEBUG, and MINER. The default is: ETH, NET, WEB3.

Note

IBFT 2.0 is under development and will be available in v1.0.

Tip

The singular --rpc-ws-api and plural --rpc-ws-apis are available and are just two names for the same option.

rpc-ws-host

--ws-host=<HOST>
# to listen on all interfaces
--ws-host=0.0.0.0
ws-host="0.0.0.0"

Host for Websocket WS-RPC to listen on. The default is 127.0.0.1.

To allow remote connections, set to 0.0.0.0

Note

This option is not used when running Pantheon from the Docker image.

rpc-ws-port

--ws-port=<PORT>
# to listen on port 6174
--ws-port=6174
ws-port="6174"

Port for Websocket WS-RPC to listen on. The default is 8546.

Note

This option is not used when running Pantheon from the Docker image.

rpc-ws-refresh-delay

--rpc-ws-refresh-delay=<refresh delay>
--rpc-ws-refresh-delay="10000"

Refresh delay for Websocket synchronizing subscription in milliseconds. The default is 5000.

help

-h, --help

Show the help message and exit.

logging

-l, --logging=<LEVEL>
--logging=DEBUG
logging="DEBUG"

Sets the logging verbosity. Log levels are OFF, FATAL, WARN, INFO, DEBUG, TRACE, ALL. Default is INFO.

version

  -V, --version

Print version information and exit.

Commands

Pantheon subcommands are:

blocks

This command provides blocks related actions.

import

$ pantheon blocks import --from=<block-file>
$ pantheon blocks import --from=/home/me/me_project/mainnet.blocks

Imports blocks from the specified file into the blockchain database

public-key

This command provides node public key related actions.

export

$ pantheon public-key export --to=<key-file>
$ pantheon public-key export --to=/home/me/me_project/not_precious_pub_key

Exports node public key to the specified file.

password-hash

This command generates the hash of a given password.

$ pantheon password-hash <my-password>
$ pantheon password-hash "password123"
Questions or feedback? You can discuss issues and obtain free support on Pegasys Pantheon Gitter room.
For paid professional support by PegaSys, contact us at [email protected]