Become a Power User of Forge CLI
By wangshijun on 07/09/2019

Become a Power User of Forge CLI

Brought to you by wangshijun

Become a Power User of Forge CLI

Become a Power User of Forge-CLI

Table of contents

  1. Setup
  2. Chain/Node Management
  3. Web Interface
  4. Read/Write Blockchain Data
  5. Deploy Tx Protocols
  6. Bootstrap dApps
  7. Forge Release Management
  8. Simulator/Workshop
  9. Customization
  10. Troubleshooting

Part 1: Setup


Requires Node.js v8.x and upper.

npm install -g @arcblock/forge-cli
yarn global add @arcblock/forge-cli

List Supported Commands



forge -h
forge --help

Initial Setup

forge install latest
forge install v0.32.2
forge install 0.32.2

For Developers from China:

forge install --mirror
forge install v0.32.2 --mirror

Part 2: Chain/Node Management

Start Single Node Chain

Start forge and forge web interface

forge start

Note: If you have a local test chain or a running forge, please cleanup first:

forge stop --force
forge reset --yes
forge start

Check Chain/Node Status

forge status
forge status chain
forge status node

Note: run forge status -h for more available options.

List Running Forge Processes

❯ forge ps
│ Name          │ PID      │ Uptime        │ Memory        │ CPU                │
│ starter       │ 77122    │ 1h 50s        │ 10.2 MB       │ 0.04 %             │
│ forge         │ 77139    │ 1h 50s        │ 53.1 MB       │ 2.93 %             │
│ tendermint    │ 77176    │ 1h 49s        │ 42.6 MB       │ 0.75 %             │

View Forge Config

  • Config file location: ~/.forge_cli/forge_release.toml
  • Config documentation:
forge config

View config that can be sent to others to join, be caution of intranet IP:

forge config --peer

Edit Forge Config

Can edit chainId/tokenInfo/pokeInfo/moderatorInfo. Only work when forge is stopped.

forge config set

Stop the Chain/Node

Stop gracefully:

forge stop

Stop aggressive: useful when do cleanup

forge stop --force

Reset Chain Data

Will erase all chain data including validator keys.

forge reset           # interactive
forge reset --yes     # reset immediately

View Logs

forge logs

Join an existing chain/network

Local forge version should match the forge version used in target chain.

forge join

Upgrade Node

  • Generate a moderator wallet:
forge wallet:create
  • Export moderator sk:
export FORGE_MODERATOR_SDK="0x1234567890"
  • Download a newer version
forge download v0.32.2
  • Send upgrade tx
forge upgrade

Part 3: Web Interface

Open the Web Interface

forge web start # should be started automatically with forge
forge web open

Note: a running web interface provides the graphql endpoint for dApps to use.

Stop the Web Interface

Graceful stop:

forge web stop

Part 4: Read/Write Blockchain Data

How to create a on chain account?

❯ forge account:create
? Please input passphrase: [hidden]
? Please input moniker: wangshijun
? Please select a role type: ROLE_ACCOUNT
? Please select a key pair algorithm: ED25519
? Please select a hash algorithm: SHA3
✔ account create success!
  sk: 'z5lVgXRjOAK6V7EbhttGWcgfE9dVEMYjMI06OiqfbNBFMLf2oMUCJN/a2bhsspVcuYngEJ1BTS64ptXID/7Tqw==',
  pk: 'RTC39qDFAiTf2tm4bLKVXLmJ4BCdQU0uuKbVyA/+06s=',
  address: 'z1e6Y69Wf2GTWcs9mEPwAbnwwtRyzH36zem'
✔ account unlocked!
ℹ run forge account z1e6Y69Wf2GTWcs9mEPwAbnwwtRyzH36zem to inspect account state

How to inspect account?

❯ forge account z1e6Y69Wf2GTWcs9mEPwAbnwwtRyzH36zem
Account Type: {
  role: 'ROLE_ACCOUNT',
  pk: 'ED25519',
  hash: 'SHA3'
Account State: {
  balance: '0 TOKEN',
  nonce: 2,
  numTxs: 1,
  address: 'z1e6Y69Wf2GTWcs9mEPwAbnwwtRyzH36zem',
  pk: 'RTC39qDFAiTf2tm4bLKVXLmJ4BCdQU0uuKbVyA/+06s=',
  moniker: 'wangshijun',
  issuer: '',
  gasBalance: '0',
  migratedTo: [],
  migratedFrom: [],
  numAssets: 0,

How to inspect transaction?

forge tx:list
❯ forge tx B59CD58C079501A6196C022F80B1B706D0B20E6A7D715BA69E10F32BB3D44474
  from: 'f1dbc43ab7aaa2407395564a7ab12029f18762be4',
  nonce: 2,
  signature: 'EWnLDOLwedU+2Ny5avEXyw+vVxX0/SJK2EWFwNPewZ3Ppg5dPiWWA9VWylreKKbm98e5DBlozfqzPrfHfsRmAg==',
  chainId: 1,
  signatures: [],
  itx: {
    to: 'f89cb04c4b31bbffde5fcbc79faab7e6b619921e4',
    value: '5946',
    assets: [],
    confirmation: false

How to inspect a block?

❯ forge block -h
Usage: block [options] [height]

Get the block info from the running node

  -d, --show-txs  Show transaction details
  -f, --stream    Streaming new blocks on the chain
  -h, --help      output usage information

  - forge block                display latest block, txs not printed
  - forge block -f             Streaming for new blocks generated
  - forge block --show-txs     display latest block, txs printed
  - forge block 123            display block at height 123
  - forge block last           display latest block
  - forge block first          display first block
  - forge block 123,456        display 2 blocks
  - forge block 1...4          display block from height 1,2,3,4

How to inspect an asset?

forge asset z1e6Y69Wf2GTWcs9mEPwAbnwwtRyzH36zem

Part 5: Deploy Transaction Protocol


  • brew install protobuf
  • mix escript.install hex protobuf

Prepare a transaction protocol: protobuf


syntax = "proto3";
package forge_abi;

message CreateProductTx {
  Product product = 1;

message Product {
  string name = 1;
  string brand = 2;

Prepare a transaction protocol: config


name: create_product
version: 1
namespace: CoreTx
description: Create product that can be sold within the vending machine
  fg:t:create_product: ForgeAbi.CreateProductTx
  fg:x:product: ForgeAbi.Product
proto: protocol.proto

Compile a transaction protocol

❯ forge protocol:compile .
ℹ protocol meta: {"name":"create_product","version":1}

ℹ generating elixir language support:
✔ elixir itx generated: .compiled/create_product/elixir/create_product/create_product.itx.json

ℹ generating javascript language support:
✔ protobuf js generated: .compiled/create_product/javascript/protocol_pb.js
✔ json spec generated: .compiled/create_product/javascript/protocol_spec.json
✔ type urls json generated: .compiled/create_product/javascript/protocol_url.json
✔ javascript entry file generated: .compiled/create_product/javascript/index.js

Note: will install forge-compiler and protobuf tools when run for first time.

Deploy a transaction protocol

❯ forge protocol:deploy .compiled/create_product/elixir/create_product/create_product.itx.json
ℹ moderator address z1VFy8hB9ndynkWAAH9P1a2L5WaU7AvtKGy
ℹ moderator declared 4B7C4AA4DD7014D3DD97F55B7A626FB35654D004A35E38943A52916B8FD6276D
✔ moderator declared on chain
ℹ deploy protocol to tcp://
transaction protocol detail {
  address: 'z2E3q3PUNCzMNvKi1RuT7KHJ7VnUGZMhjPQwF',
  name: 'create_product',
  version: 1,
  namespace: 'CoreTx',
  description: 'Create product that can be sold within the vending machine',
  tagsList: [],
  data: undefined
✔ transaction protocol deploy success
ℹ inspect tx with forge tx 167EF5C9DEC3411599B790793DEE73B1FB94DD7ECB3AA28DDA7FC6AF14E04F40

Part 6: Bootstrap dApps

Install an dApp starter

Should have a local chain up and running.

# Install a dapp starter
npm install -g forge-react-starter
npm install -g forge-next-starter
npm install -g forge-keystone-starter

More starters can be found at dapp starters repo.

Create a project form the starter

Create skeleton

# Create the dapp interactively
forge create-project /tmp/hello-forge

# Create the dapp with default options
forge create-project --yes /tmp/hello-forge

Start the dapp

cd /tmp/hello-forge
yarn start

Try the dapp in your browser with ABT Wallet.

Part 7: Forge Release Management

List installed releases

Check mark indicates current version.

❯ forge ls
Forge Kernel:
  ✓ 0.32.2

Forge Starter:
  ✓ 0.32.2

Forge Web:
  ✓ 0.32.2

  ✓ 0.32.2

Download a release without activate

Very similar to forge install.

❯ forge download v0.31.1 --mirror
ℹ Detected platform is: darwin
⚠ forge version 0.32.2 already initialized: /Users/wangshijun/.forge_cli/release
✔ Release asset info fetch success forge_darwin_amd64.tgz
ℹ Start download
ℹ Downloading forge_darwin_amd64.tgz |████████████████████████████████████████ 100% || 40.30/40.30 MB
✔ Downloaded forge_darwin_amd64.tgz to /Users/wangshijun/.forge_cli/tmp/forge_darwin_amd64.tgz
✔ Expand release asset /Users/wangshijun/.forge_cli/tmp/forge_darwin_amd64.tgz to /Users/wangshijun/.forge_cli/release/forge/0.31.1
✔ Release asset info fetch success forge_starter_darwin_amd64.tgz
ℹ Start download
✔ Congratulations! forge v0.31.1 download successfully!

Now you can use this version with forge use 0.31.1, requires reset chain state
Or you can upgrade to this version with forge upgrade, does not requires reset chain state

Activate an installed forge release

  • Requires reset chain state, otherwise forge will not start
  • Switch version should be done when forge stopped
  • We recommend use forge upgrade instead of manual version switch
forge use v0.31.1

Part 8: Simulator/Workshop

How to start/stop the Simulator

Generate some test traffic on your test chain.

forge simulator start
forge simulator stop

How to start/stop the Workshop

Create application did auth workflow. Need ABT Wallet on your phone.

forge workshop start
forge workshop stop

Part 9: Customization

Use custom forge config

FORGE_CONFIG=/path/to/config.toml forge start


forge start --config-path /path/to/config.toml

Use custom platform

Not recommended.

FORGE_CLI_PLATFORM=centos forge install latest

Use custom release directory

Use with caution, default release dir is ~/.forge_cli/release.

FORGE_RELEASE_DIR=/path/to/release forge start


forge start --release-dir /path/to/release

Use custom grpc endpoint

FORGE_SOCK_GRPC=tcp:// forge status


forge status --socket-grpc tcp://

Part 10: Troubleshooting & Debugging

Show detailed help

Try the following commands, replace block with any valid subcommand.

forge --help
forge help block
forge block -h
forge block --help

Verbose mode

Run any command with --verbose flag

forge status --verbose
forge start --verbose

Report an issue

  1. Run the failed command with --verbose flag
  2. Run forge version to get the software version
  3. Create issues on our github repo.