# Command Line Interface

# Installation

Since Version 2.2.0 we distribute the Swipechain 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 @swipechain/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 swipechain
usermod -aG sudo swipechain
su swipechain
cd ~
bash <(curl -s https://raw.githubusercontent.com/Swipechain/swipechain-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/@swipechain/core for new releases or use swipechain update to check for updates.

# Configuration

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

swipechain 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 swipechain 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 && swipechain relay:start && pm2 logs, also swipechain 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 Swipechain CLI does support. Using this command does not configure autocompletion, but does show you instructions.

# Usage

swipechain autocomplete

# config:cli

Configure the CLI

# Usage

swipechain config:cli

# Flags

# Examples

# Use the "mine" token for configuration

swipechain config:cli --token="mine"

# Switch to the Beta Channel

swipechain config:cli --channel="beta"

# config:database

Configure the database

# Usage

swipechain config:database

# Flags

# Examples

swipechain config:database --host=localhost --port=5432 --database=ark_mainnet --username=swipechain --password=password

# config:forger

Configure the forging delegate

# Usage

swipechain config:forger

# Flags

# Examples

# Configure a Delegate Using an Encrypted BIP38

swipechain config:forger --method=bip38 --bip39="..." --password="..."

# Configure a Delegate Using a BIP39 Passphrase

swipechain config:forger --method=bip39 --bip39="..."

# config:forger:bip38

Configure a delegate using an encrypted BIP38

# Usage

swipechain config:forger:bip38

# Flags

# Examples

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

# config:forger:bip39

Configure a delegate using a BIP39 passphrase

# Usage

swipechain config:forger:bip39

# Flags

# Examples

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

# config:publish

Publish the configuration

# Usage

swipechain config:publish

# Flags

# Examples

# Publish the Configuration

swipechain config:publish

# config:reset

Reset the configuration

# Usage

swipechain config:reset

# Flags

# Examples

# Reset the Configuration for the Mainnet Network

swipechain config:reset --network=mainnet

# core:log

Show the core log

# Usage

swipechain core:log

# Flags

# Examples

swipechain core:log

# core:restart

Restart the core

# Usage

swipechain core:restart

# Flags

# Examples

# Restart the Core

swipechain core:restart

# core:start

Start the core

# Usage

swipechain core:start

# Flags

# Examples

# Run Core With a Daemon

swipechain core:start

# Run Core as Genesis

swipechain core:start --networkStart

# Disable Any Discovery by Other Peers

swipechain core:start --disableDiscovery

# Skip the Initial Discovery

swipechain core:start --skipDiscovery

# Ignore the Minimum Network Reach

swipechain core:start --ignoreMinimumNetworkReach

# Start a Seed

swipechain core:start --launchMode=seed

# Run Core Without a Daemon

swipechain core:start --no-daemon

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

swipechain core:run

# core:stop

Stop the core

# Usage

swipechain core:stop

# Flags

# Examples

# Stop the Core

swipechain core:stop

# Stop the Core Daemon

swipechain core:stop --daemon

# env:get

Get the value of an environment variable

# Usage

swipechain env:get KEY

# Flags

# Examples

# Get the Log Level

swipechain env:get CORE_LOG_LEVEL

# env:list

List all environment variables

# Usage

swipechain env:list

# Flags

# Examples

# List All Environment Variables

swipechain env:list

# env:paths

Get all of the environment paths

# Usage

swipechain env:paths

# Flags

# Examples

# List All Environment Paths

swipechain env:paths

# env:set

Set the value of an environment variable

# Usage

swipechain env:set KEY VALUE

# Flags

# Examples

# Set the Log Level

swipechain env:set CORE_LOG_LEVEL info

# forger:log

Show the forger log

# Usage

swipechain forger:log

# Flags

# Examples

swipechain forger:log

# forger:restart

Restart the forger

# Usage

swipechain forger:restart

# Flags

# Examples

# Restart the Forger

swipechain forger:restart

# forger:start

Start the forger

# Usage

swipechain forger:start

or the equivalent, without invoking pm2:

swipechain forger:run

# Flags

# Examples

# Run a Forger With a bip39 Passphrase

swipechain forger:start --bip39="..."

# Run a Forger With an Encrypted bip38

swipechain forger:start --bip38="..." --password="..."

# Run a Forger Without a Daemon

swipechain forger:start --no-daemon

# forger:stop

Stop the forger

# Usage

swipechain forger:stop

# Flags

# Examples

# Stop the Forger

swipechain forger:stop

# Stop the Forger Daemon

swipechain forger:stop --daemon

# forger:status

Show the forger status.

# Usage

swipechain forger:status

# Flags

# Example

swipechain forger:status

# relay:log

Show the relay log

# Usage

swipechain relay:log

# Flags

# Examples

swipechain relay:log

# relay:restart

Restart the relay

# Usage

swipechain relay:restart

# Flags

# Examples

# Restart the Relay

swipechain relay:restart

# relay:start

Start the relay

# Usage

swipechain relay:start

or the equivalent without using pm2:

swipechain relay:run

# Flags

# Examples

# Run a Relay With a pm2 Daemon

swipechain relay:start --network=mainnet

# Run a Genesis Relay

swipechain relay:start --networkStart

# Disable Any Discovery by Other Peers

swipechain relay:start --disableDiscovery

# Skip the Initial Discovery

swipechain relay:start --skipDiscovery

# Ignore the Minimum Network Reach

swipechain relay:start --ignoreMinimumNetworkReach

# Start a Seed

swipechain relay:start --launchMode=seed

# Run a Relay Without a Daemon

swipechain relay:start --no-daemon

# relay:stop

Stop the relay

# Usage

swipechain relay:stop

# Flags

# Examples

# Stop the Relay

swipechain relay:stop

# Stop the Relay Daemon

swipechain relay:stop --daemon

# top

List all core daemons

# Usage

swipechain top

# Examples

# List All Core Daemons

swipechain top

# snapshot:dump

Create a dump of the database

# Usage

swipechain snapshot:dump

# Flags

# snapshot:restore

Restore the database from a dump

# Usage

swipechain snapshot:restore

# Flags

# snapshot:rollback

Roll back the database to a specific height or by a specified number of blocks

# Usage

swipechain snapshot:rollback

# Flags

# snapshot:truncate

Truncate the database

# Usage

swipechain snapshot:truncate

# snapshot:verify

Create a new snapshot

# Usage

swipechain snapshot:verify

# Flags

# Plugins

Core itself is composed of multiple plugins that once stitched together provide the full system needed to interact with the Swipechain 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 @swipechain/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 @swipechain/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/swipechain-core/{NETWORK}/plugins.js file. Open the file in your editor of choice, append the following contents and save the changes.

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

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