CLI Commands

Credentials

To add your credentials, run the command:

harbor configure keys

This will prompt you to add in both your Project and User Key. Paste your Project Key and User Key, and hit enter:

Updating existing credentials file...
user_key: n5kf6gdWZzciDsGiSHdAfz
project_key: kEuTW4o3R4AV1nb298gumB
successfully configured harbor with credentials
now you can run harbor build on a configuration file!

We can surpass these prompts by adding the flags, user-key and project-key. If we add the user-key flag and pass in the User Key value, then we will not be prompted for the User Key. Here's an example:

harbor configure keys --user-key n5kf6gdWZzciDsGiSHdAfz

Similarly, if we add the project-key flag along with the Project Key value, then we will not be prompted for the Project Key. Example command:

harbor configure keys --project-key kEuTW4o3R4AV1nb298gumB

Adding both the project-key and the user-key in a command will not prompt us to add any keys. The command looks like this:

harbor configure keys --user-key n5kf6gdWZzciDsGiSHdAfz --project-key kEuTW4o3R4AV1nb298gumB

For more information, learn how to manage your credentials.

Quickstart

Quick starting your Testnet is simple. If you just want a Testnet running with an ethereum chain and you don't want to worry about your configuration and your off-chain actors, then run this command:

harbor quickstart <testnet-name>

This will give you the log:

🌍 Testnet create/update in progress...  [1m59s]

Until the Testnet runs. You should be given one ethereum chain along with its endpoint in the following format:

##### 1 Chains

Chain = ⛓ ethereum
Status = ✔️ RUNNING
Endpoint = 🌎 http://13.127.195.221:4000

###### 0 Off-chain actors

Use the endpoint to interact with your Testnet.

Editing the configuration file via the CLI

Add chain

If you are in the same directory as your configuration, you can add a chain by running:

harbor configure add chain <flags>

You can add the following flags:

artifacts-path: the path to the chain's smart contract artifacts
chain-id the id to be used for the chain
depends-on the dependencies for the chain
deploy-path the path to the chain's smart contract deploy folder
config specifies the location of the config file you want to modify
include-paths the paths to be included while building the chain
name the name of the chain. Accepted names are:
- ethereum
- arbitrum
- polygon
- avalanche
- fantom
- optimism
tag the string that identifies the current version of the off-chain actor
- If we are updating the actor, then we must add a new tag value and run harbor apply <testnet-name>
- Only + - = . _ : / @ are allowed as special characters
wallet the number of wallets
token the symbol(s) of coins needed. Examples are:
- ETH
- DAI
amount the number of tokens, respectively according to the order of the token symbols provided.

The artifacts-path, deploy-path, name, and tag are all mandatory flags.

Example

To add a simple chain:

harbor configure add chain --name ethereum --artifacts-path /path/to/artifacts/ --deploy-path /path/to/deploy --tag v1 --config harbor.config.json

This will give us a config file with the output:

{
  "chains": [
    {
      "chain": "ethereum",
      "config": {
        "artifactsPath": "/path/to/artifacts/",
        "deploy": { "scripts": "/path/to/deploy" }
      },
      "tag": "v1"
    }
  ]
}

Add off-chain actor(s)

To add an off-chain actor, run the command:

harbor configure add off-chain-actor <flags>

The accepted flags are:

build-path the build path pointing towards the Dockerfile directory for our off-chain actor
command the command to be used for the off-chain actor
config specifies the location of the config file you want to modify
depends-on is the array of dependencies for the off-chain actor
docker-file the path to the Dockerfile of the off-chain actor
env array containing environment variables to be set
image the public image that the off-chain actor will be based off
name the name of the actor
ports the array of specified ports for the actor
schedule-exp the cron schedule expression for the off-chain actor which determines the frequency with which the actor has to be invoked.
- i.e: rate (1 minute) as a value of schedule-exp means that the off-chain actor is invoked every 1 minute
tag the string that identifies the current version of the off-chain actor
- If we are updating the actor, then we must add a new tag value and run harbor apply <testnet-name>
- Only + - = . _ : / @ are allowed as special characters

The image (if public image actor) or docker-file/build-path (if locally built actor), name, ports, and tag are all mandatory flags.

Example

To add a simple off-chain actor:

harbor configure add off-chain-actor --name ipfs --image ipfs/go-ipfs:v0.4.23 --ports 5000 --tag v1 --config harbor.config.json

This will give us the configuration:

{
  "offChainActors": [
    {
      "name": "ipfs",
      "image": "ipfs/go-ipfs:v0.4.23",
      "ports": [5000],
      "tag": "v1"
    }
  ]
}

caution

The name of an off-chain actor cannot be more than 20 characters!

Apply configuration

Before applying your configuration, make sure that the tag key is filled with any text. You can't run your Testnet if the tag value is empty.

When you are done creating your Testnet configuration, you can create a Testnet out of it. To do so, run the following command in the same directory as the configuration:

harbor apply <testnet-name>

Where <testnet-name> is a name of your choice.

Alternatively, you can use the flag --config-file and specify the path to your config file if it's in a different directory:

harbor apply <testnet-name> --config /path/to/harbor.config.json

This is especially useful when you have multiple configs off the same Testnet.

If you make new changes to your config, like adding a new actor, updating an existing port of an actor, etc. you need to make sure that you overwrite the existing tag on any of the actors that you've changed. Afterwards, running harbor apply <testnet-name> again will apply the diff between the old configuration and the new one.

Managing Testnet

Editing Testnet

While a Testnet is running, you can add, update, remove, stop or start actors. After running these commands, you must wait a few minutes so that the Testnet updates to the latest configuration.

The configure command differs from the edit command as the configure command modifies the configuration file. The edit command, on the other hand, modifies an already running Testnet.

Add actors

To add an actor, run the command:

harbor edit <testnet-name> add <actor-name> <additional-flags> --tag <tag-name>

If the actor-name is a name of a chain (i.e: ethereum), then Harbor automatically adds the actor as a chain. Any name that's not a chain will be added as an off-chain actor.

You must use additional flags to successfully add an actor. Otherwise, the command will fail. One flag that is mandatory for actors is the tag flag. Let's explore the rest below.

Add chain

The minimum requirements for adding a chain are four:

<chain-name> must be recognized by Harbor
artifacts-path path to your compiled contracts directory
deploy-path path to your deploy scripts directory
tag the string that identifies the current version of the chain
- If we are updating the chain, then we must add a new tag value and run harbor apply <testnet-name>
- Only + - = . _ : / @ are allowed as special characters
wallet the number of wallets
token the symbol(s) of coins needed. Examples are:
- ETH
- DAI
amount the number of tokens, respectively according to the order of the token symbols provided.

Here is a list of chain names recognized by Harbor:

So, to add a polygon chain with a certain artifacts path, run:

harbor edit <testnet-name> add polygon --artifacts-path /path/to/artifacts/  --deploy-path /path/to/deploy/ --tag polygon-v1

If you don't provide a valid artifacts-path, deploy-path, and tag name, then the command will fail.

Adding wallets to a chain

Adding wallets

When we add a chain, we can add one with wallets. To do so, run the following:

harbor edit <testnet-name> add ethereum --artifacts-path /path/to/artifacts/ --deploy-path /path/to/deploy/ --wallet 2 --token matic --amount 1000 --tag polygon-tag

This will add ethereum, with 2 wallets containing 1000 matic.

caution

As of November 29th, 2022:

If you are adding non-base tokens for anything other than the Ethereum chain, we don't support that yet
If you are trying to set the amount of the base token (ETH for Ethereum, AVAX for Avalanche, MATIC for Polygon, etc.), then Harbor will just automatically set the amount to the default 10,000 tokens

To see the list of all tokens supported in Ethereum, check them out here.

Add off-chain actors

The minimum requirements for adding an off-chain actor are two:

<actor-name> must not be a name of a chain
image flag must be provided OR
docker-file flag along with build-path must also be provided

So to add an off-chain actor with a public image, run:

harbor edit <testnet-name> add postgres1337 --image postgres --tag postgres-tag

Otherwise, to add an off-chain actor with a Dockerfile, run:

harbor edit <testnet-name> add liquidationBot --docker-file /path/to/dockerfile --build-path /path/to/buildpath --tag liquidation-tag

Update actors

You can also update the attributes within an actor. Suppose you'd like to update the port with an additional value of an off-chain actor:

harbor edit <testnet-name> update <actor-name> --ports <value> --tag port-tag

Running the above command will give us:

🌍 Testnet create/update in progress...  [1m39s]

Updating a wallet

If we have a chain running in a Testnet, we can add wallets within. To do this, run the command:

harbor edit <testnet-name> update <chain-name> --wallet 3 --token eth,matic --amount 100,1000 --tag v2

If we already had wallets in this chain, the above command replaces them and resets the number of tokens in the chain. If we didn't have wallets, then the above command adds the wallets into the chain.

Stop actors

To stop an actor from running in a Testnet, run the command below:

harbor edit <testnet-name> stop <actor-name>

Remove actors

What if you wanted to completely remove an actor from a Testnet? To do just that, you must run:

harbor edit <testnet-name> remove <actor-name>

List Testnets

To see a list of your Testnets, run the command:

harbor list testnet

This will give us:

listing testnets...
+--------------------------------------+-----------------------------+--------+--------------------------------+
|                  ID                  |            NAME             | STATUS |            CREATED             |
+--------------------------------------+-----------------------------+--------+--------------------------------+
| fa96c88a-e518-49dd-80ab-dc15063fd6a0 | testnet-name-1              | ACTIVE | 2022-09-26 07:47:56.266345     |
|                                      |                             |        | +0000 +0000                    |
| 0e643cb7-5cd7-460b-b740-08a0b56a48d4 | testnet-name-2              | ACTIVE | 2022-09-27 13:54:22.187643     |
|                                      |                             |        | +0000 +0000                    |
| dd9ce4a8-084b-4278-984d-b2858a137ce2 | testnet-name-3              | ACTIVE | 2022-09-28 04:53:17.585098     |
|                                      |                             |        | +0000 +0000                    |
+--------------------------------------+-----------------------------+--------+--------------------------------+

Add other credentials if you'd like to see Testnets related to those credentials.

Killing your Testnet

To kill your Testnet by its Testnet ID, run the command:

harbor kill --name <testnet-name>

Killing a Testnet means to stopping it from running. Once we have stopped it from running, we can start it again.

Starting your Testnet

To start your killed Testnet, run the command:

harbor start <testnet-name>

Where <testnet-name> is the name of your killed Testnet.

Cloning your Testnet

To clone your Testnet, run the command:

harbor clone <source-testnet-name> <new-testnet-name>

This command works exactly like running a new Testnet, with the exception that you are using the <source-testnet-name> configuration for the <new-testnet-name> configuration.

Understanding Testnets

As long as your Testnet is running, you can find out information on its endpoints and actors.

Describe Testnet

Execute the command below to get a description of all your Testnet's actors and endpoints:

harbor describe testnet --name <testnet_name>

This will give you the Testnet information in the following format:

Testnet name: sample-testnet-name
+----------+---------+---------------------------+
|  CHAINS  | STATUS  |         ENDPOINT          |
+----------+---------+---------------------------+
| ethereum | RUNNING | http://34.213.53.1:3000 |
+----------+---------+---------------------------+

Total chains count: 1
+--------+---------+---------------------------+
| ACTORS | STATUS  |         ENDPOINT          |
+--------+---------+---------------------------+
| ipfs   | RUNNING | http://43.205.242.46:5000 |
+--------+---------+---------------------------+

Total off-chain actors count: 1

 Wallets and Contracts for chain ethereum
+--------------------------------------------+----------+---------+-------------------------------+----------+
|                  ADDRESS                   |   TYPE   |  NAME   |            BALANCE            |  CHAIN   |
+--------------------------------------------+----------+---------+-------------------------------+----------+
| 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 | wallet   | -       | ETH-9999999068271250000000,   | ethereum |
| 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 | wallet   | -       | ETH-10000000000000000000000,  | ethereum |
| 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC | wallet   | -       | ETH-10000000000000000000000,  | ethereum |
| 0x5FbDB2315678afecb367f032d93F642f64180aa3 | contract | Greeter | ETH-0,                        | ethereum |
+--------------------------------------------+----------+---------+-------------------------------+----------+

You can also output the Testnet information in a JSON format. To do this, add in an extra output flag followed by json as the value. Like this:

info

The output flag only works if we find the testnet using the name flag.

harbor describe testnet --name <testnet_name> --output json

This will give you:

{
  "name": "test",
  "chains": {
    "ethereum": {
      "status": "STOPPED",
      "endpoint": "http://34.213.53.1:3000"
    }
  },
  "offChainActors": {
    "ipfs": {
      "status": "STOPPED",
      "endpoints": ["43.205.242.46:5000"]
    }
  }
}

Using the actor name, you can find logs concerning a specific Testnet actor.

Get actor logs

To retrieve an actor's logs, run the command:

harbor log actor --testnet-id <testnet_id> --name <chain_name/actor_name>

This will give us specific information on your actor! Example of a log below:

fa96c88a-e518-49dd-80ab-dc15063fd6a0
Attempting to connect to the database...
Connection successful
Listening on port 3000
Config reloaded
Listening for notifications on the pgrst channel
Schema cache loaded

Describe project

To find out what project you are currently on, run the command:

harbor describe project

This will give you:

Name: test
Id: 54c912a1-ecf2-4e72-8408-3cc4fb0d4575

Where Name is the name of the project and Id is the project's ID.

Bridges

Listing bridges

To list all of our bridges, run the command:

harbor list protocol

This will give you:

listing public testnets...


+----------+------------------------------+--------------------------------------+------------------+---------+
| PROTOCOL |          HOME PAGE           |              TESTNET ID              |   PROTOCOL ID    | VERSION |
+----------+------------------------------+--------------------------------------+------------------+---------+
| Axelar   | https://axelar.network/      | a99719d7-06b2-4d20-a7e0-68fabed1832a | protocol-Axelar  |     0.1 |
| Connext  | https://www.connext.network/ | d252c054-2e77-4fe7-9ba9-66e6d7e0c649 | protocol-Connext | 0.2.1   |
+----------+------------------------------+--------------------------------------+------------------+---------+

You need to copy the PROTOCOL ID of your choice before you can clone that bridge.

Cloning a bridge

With the PROTOCOL ID copied, you can clone the bridge onto a Testnet by running the command:

harbor clone <protocol-id> <new-testnet-name>

You should see:

Configuring off-chain actor compiler
Configuring off-chain actor relayer
🌍 Testnet create/update in progress...  [3m41s]

###### 2 Chains

Status = ✔ RUNNING
Chain = ⛓️ethereum
Endpoint = 🌎 http://15.206.168.114:4000

Status = ✔ RUNNING
Chain = ⛓️polygon
Endpoint = 🌎 http://15.206.168.114:4004

###### 2 Off-chain actors

Off-chain Actor = compiler
Status = ✔ RUNNING
Endpoint = 🌎 http://13.234.59.187:5432

Off-chain Actor = compiler
Status = ✔ RUNNING
Endpoint = 🌎 http://65.2.175.192:4000

This is also reflected in the UI, in the project's dashboard.

CLI Commands

Credentials​

Quickstart​

Editing the configuration file via the CLI​

Add chain​

Example​

Add off-chain actor(s)​

Example​

Apply configuration​

Managing Testnet​

Editing Testnet​

Add actors​

Add chain​

Adding wallets to a chain​

Adding wallets​

Add off-chain actors​

Update actors​

Updating a wallet​

Stop actors​

Remove actors​

List Testnets​

Killing your Testnet​

Starting your Testnet​

Cloning your Testnet​

Understanding Testnets​

Describe Testnet​

Get actor logs​

Describe project​

Bridges​

Listing bridges​

Cloning a bridge​

Credentials

Quickstart

Editing the configuration file via the CLI

Add chain

Example

Add off-chain actor(s)

Example

Apply configuration

Managing Testnet

Editing Testnet

Add actors

Add chain

Adding wallets to a chain

Adding wallets

Add off-chain actors

Update actors

Updating a wallet

Stop actors

Remove actors

List Testnets

Killing your Testnet

Starting your Testnet

Cloning your Testnet

Understanding Testnets

Describe Testnet

Get actor logs

Describe project

Bridges

Listing bridges

Cloning a bridge