Command Line Interface

Installation

Since Version 2.2.0 we distribute the Ark Core as an npm package, which has to be globally installed, which provides a built-in CLI.

Prerequisites

In the next sections we will run you through an automated setup of a new server with a Core installation at the end of it but if you prefer to do a manual setup, take a look at install.sh to see what dependencies need to be installed and configured.

A global pm2 installation is required as the CLI uses it to manage processes. Take a look at the process manager to see how it works under the hood.

Existing Installation

If you are already owning a server that runs Core 2.1.0 or newer you can simply execute the following command.

yarn global add @arkecosystem/core

This command might take a while since all packages and dependencies need to be installed as well.

Once this command has finished you should stop all your existing core processes with pm2 delete all and start new ones with one of the commands that are documented further down on this page. If you are having any issues with the CLI, head down to the Troubleshoot section which covers the most common issues we know about.

Fresh Installation

If you are planning to setup a new server you can execute the following steps.

adduser ark
usermod -aG sudo ark
su ark
cd ~
bash <(curl -s https://raw.githubusercontent.com/ArkEcosystem/core/master/install.sh)

Once this command has finished you should start your relay and forger with one of the commands that are documented further down on this page. If you are having any issues with the CLI, head down to the Troubleshoot section which covers the most common issues we know about.

You can check https://www.npmjs.com/package/@arkecosystem/core for new releases or use ark update to check for updates.

Configuration

Before you can start using Ark Core you will need to publish the configuration of the network you wish to operate on.

ark config:publish

This will bring up an interactive UI which will ask a few questions to help you with the setup process. Once you have published the configuration you can start using the CLI. It will automatically detect which network you have configured.

Troubleshooting

Most of the issues you will encounter are related to pm2 not properly responding so the first thing you can try is to kill your pm2 daemon and refresh it.

pm2 kill && pm2 cleardump && pm2 reset

If this doesn't help, read the known issues below and see if any of those solve your issues.

Command not found

If you are receiving a message to the effect of ark command not found your bash environment most likely doesn't have the yarn bin path registered. Execute the following command to resolve the issue.

echo 'export PATH=$(yarn global bin):$PATH' >> ~/.bashrc && source ~/.bashrc

If you are using a shell other then the default bash, like zsh, you will need to replace ~/.bashrc with ~/.zshrc.

Process fails to start after update

If the processes fail to start or restart after an update it is most likely an issue with pm2. Running pm2 update should usually resolve the issue.

If this doesn't resolve the issue you should run pm2 delete all && ark relay:start && pm2 logs, also ark forger:start if you are a delegate.

Process has entered an unknown state

If you are receiving a message to the effect of The "..." process has entered an unknown state. your pm2 instance is not responding properly. This is usually resolved by a simple pm2 update, if that doesn't help try pm2 kill to destroy the pm2 daemon so it gets restarted the next time an application tries to access it.

Available Commands

autocomplete

You might be used to tab completion, which the Ark CLI does support. Using this command does not configure autocompletion, but does show you instructions.

Usage

ark autocomplete

config:cli

Configure the CLI

Usage

ark config:cli

Flags

Name Description Required
--token the name of the token that should be used
--channel the npm registry channel that should be used

Examples

Use the "mine" token for configuration
ark config:cli --token="mine"
Switch to the beta channel
ark config:cli --channel="beta"

config:forger

Configure the forging delegate

Usage

ark config:forger

Flags

Name Description Required
--bip39 the plain text bip39 passphrase
--password the password for the encrypted bip38
--method the configuration method to use (bip38 or bip39)
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Configure a delegate using an encrypted BIP38
ark config:forger --method=bip38 --bip39="..." --password="..."
Configure a delegate using a BIP39 passphrase
ark config:forger --method=bip39 --bip39="..."

config:forger:bip38

Configure a delegate using an encrypted BIP38

Usage

ark config:forger:bip38

Flags

Name Description Required
--bip39 the plain text bip39 passphrase
--password the password for the encrypted bip38
--network the name of the network that should be used
--token the name of the token that should be used

Examples

ark config:forger:bip38 --bip38="..." --password="..."

config:forger:bip39

Configure a delegate using a BIP39 passphrase

Usage

ark config:forger:bip39

Flags

Name Description Required
--bip39 the plain text bip39 passphrase
--network the name of the network that should be used
--token the name of the token that should be used

Examples

ark config:forger:bip39 --bip39="..."

config:publish

Publish the configuration

Usage

ark config:publish

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Publish the configuration
ark config:publish

config:reset

Reset the configuration

Usage

ark config:reset

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Reset the configuration for the mainnet network
ark config:reset --network=mainnet

core:log

Show the core log

Usage

ark core:log

Flags

Name Description Required
--error only show error output
--network the name of the network that should be used
--token the name of the token that should be used

Examples

ark core:log

core:restart

Restart the core

Usage

ark core:restart

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Restart the core
ark core:restart

core:start

Start the core

Usage

ark core:start

Flags

Name Description Required
--bip39 the plain text bip39 passphrase
--bip38 the encrypted bip38
--password the password for the encrypted bip38
--[no-]daemon start the process as a pm2 daemon
--disableDiscovery permanently disable any peer discovery
--ignoreMinimumNetworkReach ignore the minimum network reach on start
--launchMode the mode the relay will be launched in (seed only at the moment)
--networkStart indicate that this is the first start of seeds
--skipDiscovery skip the initial peer discovery
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Run core with a daemon
ark core:start
Run core as genesis
ark core:start --networkStart
Disable any discovery by other peers
ark core:start --disableDiscovery
Skip the initial discovery
ark core:start --skipDiscovery
Ignore the minimum network reach
ark core:start --ignoreMinimumNetworkReach
Start a seed
ark core:start --launchMode=seed
Run core without a daemon
ark core:start --no-daemon

or use the following command, which supports the same set of flags.:

ark core:run

core:stop

Stop the core

Usage

ark core:stop

Flags

Name Description Required
--daemon stop the process or pm2 daemon
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Stop the core
ark core:stop
Stop the core daemon
ark core:stop --daemon

env:get

Get the value of an environment variable

Usage

ark env:get KEY

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Get the log level
ark env:get CORE_LOG_LEVEL

env:list

List all environment variables

Usage

ark env:list

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

List all environment variables
ark env:list

env:paths

Get all of the environment paths

Usage

ark env:paths

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

List all environment paths
ark env:paths

env:set

Set the value of an environment variable

Usage

ark env:set KEY VALUE

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Set the log level
ark env:set CORE_LOG_LEVEL info

forger:log

Show the forger log

Usage

ark forger:log

Flags

Name Description Required
--error only show error output
--network the name of the network that should be used
--token the name of the token that should be used

Examples

ark forger:log

forger:restart

Restart the forger

Usage

ark forger:restart

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Restart the forger
ark forger:restart

forger:start

Start the forger

Usage

ark forger:start

or the equivalent, without invoking pm2:

ark forger:run

Flags

Name Description Required
--bip39 the plain text bip39 passphrase
--bip38 the encrypted bip38
--password the password for the encrypted bip38
--[no-]daemon start the process as a pm2 daemon
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Run a forger with a bip39 passphrase
ark forger:start --bip39="..."
Run a forger with an encrypted bip38
ark forger:start --bip38="..." --password="..."
Run a forger without a daemon
ark forger:start --no-daemon

forger:stop

Stop the forger

Usage

ark forger:stop

Flags

Name Description Required
--daemon stop the process or pm2 daemon
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Stop the forger
ark forger:stop
Stop the forger daemon
ark forger:stop --daemon

forger:status

Show the forger status.

Usage

ark forger:status

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Example

ark forger:status

relay:log

Show the relay log

Usage

ark relay:log

Flags

Name Description Required
--error only show error output
--network the name of the network that should be used
--token the name of the token that should be used

Examples

ark relay:log

relay:restart

Restart the relay

Usage

ark relay:restart

Flags

Name Description Required
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Restart the relay
ark relay:restart

relay:start

Start the relay

Usage

ark relay:start

or the equivalent without using pm2:

ark relay:run

Flags

Name Description Required
--[no-]daemon start the process as a pm2 daemon
--disableDiscovery permanently disable any peer discovery
--ignoreMinimumNetworkReach ignore the minimum network reach on start
--launchMode=launchMode the mode the relay will be launched in (seed only at the moment)
--networkStart indicate that this is the first start of seeds
--skipDiscovery skip the initial peer discovery
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Run a relay with a pm2 daemon
ark relay:start --network=mainnet
Run a genesis relay
ark relay:start --networkStart
Disable any discovery by other peers
ark relay:start --disableDiscovery
Skip the initial discovery
ark relay:start --skipDiscovery
Ignore the minimum network reach
ark relay:start --ignoreMinimumNetworkReach
Start a seed
ark relay:start --launchMode=seed
Run a relay without a daemon
ark relay:start --no-daemon

relay:stop

Stop the relay

Usage

ark relay:stop

Flags

Name Description Required
--daemon stop the process or pm2 daemon
--network the name of the network that should be used
--token the name of the token that should be used

Examples

Stop the relay
ark relay:stop
Stop the relay daemon
ark relay:stop --daemon

top

List all core daemons

Usage

ark top

Examples

List all core daemons
ark top

snapshot:dump

Create a dump of the database

Usage

ark snapshot:dump

Flags

Name Description Required
--blocks blocks to append to, correlates to folder name
--codec codec name, default is msg-lite binary
--start [default: -1] start network height to export
--end [default: -1] end network height to export
--skipCompression skip gzip compression
--trace dumps generated queries and settings to console
--network the name of the network that should be used
--token the name of the token that should be used

snapshot:restore

Restore the database from a dump

Usage

ark snapshot:restore

Flags

Name Description Required
--signatureVerify signature verification
--skipRestartRound skip revert to current round
--blocks blocks to append to, correlates to folder name
--codec codec name, default is msg-lite binary
--start [default: -1] start network height to export
--end [default: -1] end network height to export
--skipCompression skip gzip compression
--trace dumps generated queries and settings to console
--network the name of the network that should be used
--token the name of the token that should be used

snapshot:rollback

Rollback the database to a specific height

Usage

ark snapshot:rollback

Flags

Name Description Required
--height [default: -1] block network height number to rollback
--trace dumps generated queries and settings to console
--network the name of the network that should be used
--token the name of the token that should be used

snapshot:truncate

Truncate the database

Usage

ark snapshot:truncate

snapshot:verify

Create a new snapshot

Usage

ark snapshot:verify

Flags

Name Description Required
--signatureVerify signature verification
--blocks blocks to append to, correlates to folder name
--codec codec name, default is msg-lite binary
--start [default: -1] start network height to export
--end [default: -1] end network height to export
--skipCompression skip gzip compression
--trace dumps generated queries and settings to console
--network the name of the network that should be used
--token the name of the token that should be used

Plugins

Core itself is composed of multiple plugins that once stitched together provide the full system needed to interact with the Ark Blockchain but any developer can create their own plugins and publish them.

Publishment

The first step to make your plugin available to the world after completing development is to publish it to the npm regsitry. We recommend to use yarn for this, check the official step-by-step guide by the yarn team.

Integration

Once your plugin is published it will be available to everyone via yarn add. Let's use the official, but optional, package @arkecosystem/core-vote-report as an example of how to install and configure a plugin.

Installation

First we will need to install the package using yarn global add. Since Release 2.2.0 Core is a global package that exposes a CLI, this is why we need to use yarn global add instead of yarn add, which is meant to be used during development.

yarn global add @arkecosystem/core-vote-report

Give it a second to download and install the plugin, once finished you can continue to the registration and configuration.

Configuration

Now that the plugin is downloaded and installed we can go ahead and register it in our ~/.config/ark-core/{NETWORK}/plugins.js file. Open the file in your editor of choice, append the following contents and save the changes.

{
    // some plugins...
    "@arkecosystem/core-vote-report": {},
}

Now run ark relay:restart and visit http://ip:4006/ and you should see a vote report, that's it.