Edit this page

SONM CLI Guide

SONM CLI is a command-line interface, that allow Buyer (consumer) and Supplier (owner of hardware) to interact with SONM components.

Global Flags:
  --insecure           Disable TLS for connection
  --keystore string    Keystore dir
  --node string        node endpoint (default "localhost:15030")
  --out string         Output mode: simple or json
  --timeout duration   Connection timeout (default 1m0s)
  -h --help            Help about any command
  • blacklist - Manage blacklisted addresses
    • list - Show blacklist
    • remove - Remove given address from your blacklist
  • completion - Generate shell-completion script
  • deal - Manage deals
    • close - Close given deal
    • list - Show your active deals
    • open - Open deal with given orders
    • status - Show deal status
    • quick-buy - Instantly open deal with provided ask order id and optional duration (should be less or equal comparing to ask order)
    • change-request - Request changes for deals
      • approve - Agree to change deal conditions with given change request
      • cancel - Decline given change requests
      • create - Request changes for given deal
  • help - Help about any command
  • login - Open or generate Etherum keys
  • master - Manage master and workers addresses
    • confirm - Confirm pending Worker's registration request
    • list - Show known worker's addresses
    • remove_master - Remove self from specified master
    • remove_worker - Remove registered worker
  • order - Manage orders
    • cancel - Cancel order on Marketplace
    • create - Place new Bid order on Marketplace
    • list - Show your active orders
    • purge - Remove all your orders from Marketplace
    • status - Show order stats
  • profile - Manage profiles
  • task - Tasks management
    • join - Provide network specs for joining to specified task's specific network
    • list - Show active tasks
    • logs - Retrieve task logs
    • pull - Pull committed image from the completed task
    • push - Push an image from the filesystem
    • start - Start task
    • status - Show task status
    • stop - Stop task
  • token - Manage tokens
    • allowance - Show current allowance for marketplace on sidechain network
    • balance - Show SONM token balance (ERC20)
    • deposit - Transfer funds from masterchain to SONM blockchain
    • withdraw - Transfer funds from SONM blockchain to masterchain
  • version - Show version
  • worker Worker management
    • ask-plan - Operations with ask order plan
      • create - Create new plan
      • list - Show current ask plans
      • purge - Purge all exiting ask-plans on worker
      • remove - Remove plan by ID
    • benchmark - Operations with worker benchmarks
      • purge - Remove all benchmarks from cache to rebenchmarks on next worker restart
      • remove - Remove specified benchmark from cache to rebenchmark on next worker restart
    • current - Show current worker's addr
    • devices - Show Worker's hardware
    • free_devices - Show Worker's hardware with remaining resources available for scheduling
    • maintenance - Schedule worker maintenance
    • next-maintenance - Print next scheduled maintenance
    • status - Show worker status
    • switch - Switch current worker to specified addr
    • tasks - Show tasks running on Worker

Blacklist

Manage blacklisted addresses in your personal blacklist. If you think someone is cheating you during the deal, you may close the deal and add counterparty address to your blacklist. See close deal for additional info. You cannot add someone to your blacklist manually. You may see the list of blacklisted profiles and remove address from blacklist.

Usage:

sonmcli blacklist [command]

Available Commands:

list        Show blacklist
remove      Remove given address from your blacklist

Show blacklist

Usage:

sonmcli blacklist list [addr] [flags]

Remove given address from your blacklist

Usage:

sonmcli blacklist remove <addr> [flags]

Generate shell-completion script

SONM CLI has auto-complete, and it usually works out-of-the-box for bash. If you use zsh or have issues with auto-complete in bash, you may generate and run shell-completion script manually.

Usage:

sonmcli completion <bash|zsh> [flags]

Manage deals

Usage:

sonmcli deal [command]

Available Commands:

close       Close given deal
list        Show your active deals
open        Open deal with given orders
quick buy   Instantly open deal with provided ask order id and optional duration (should be less or equal comparing to ask order)
status      Show deal status

Close given deal

Buyer may close any deal at any moment. Payments will be executed for a certain deal duration.

Supplier may close Spot deal at any moment. Payments will be executed for a certain deal duration. Supplier cannot close General (Forward, time limited) deal until deal duration is over.

Usage:

sonmcli deal close <deal_id> [flags]

Flags:

--blacklist   Add counterparty to blacklist

Show your active deals

Usage:

sonmcli deal list [flags]

Flags:

--limit uint   Deals count to show (default 10)

Open deal with given orders

The normal way to open a deal is:

For Supplier:

  • Use auto-seller bot 'Optimus' to manage your worker resources and place ASK orders to the market. Deal will open automatically when matching BID order will be placed onto the SONM marketplace by the Buyer.

For Buyer (Consumer):

  • (first option) Place BID order to the SONM marketplace. Deal will open automatically when matching ASK order will be placed onto the SONM marketplace by the Supplier's worker node.
  • (second option) Find suitable ASK order with SONM marketplace GUI and buy it.

But, in some cases it is useful to have an option to try to open a deal directly with providing two orders (BID and ASK).

Usage:

sonmcli deal open <ask_id> <bid_id> [flags]

Instantly open deal with provided ask order id and optional duration (should be less or equal comparing to ask order)

This command allow Customer to quickly open new deal with Supplier. User should specify certain ASK order ID.

Customer do not have to create new BID order to use command.

Customer may specify deal duration, that is less or equals the duration specified in Supplier’s ASK order.

If [duration] flag omitted, the deal opens under conditions specified in ASK order.

Usage:

sonmcli deal quick-buy <ask_id> [duration] [flags]

Show deal status

Usage:

sonmcli deal status <deal_id> [flags]

Request changes for deals

Any deal participant (Consumer or Supplier) may propose to counterparty to change deal conditions: price and/or duration.

Some requests affect deal conditions automatically:

  • if Supplier offers to decrease the deal price;
  • if Consumer offers to increase the deal price.

Other requests need to be confirmed by counterparty:

  • Supplier offers to increase the deal price;
  • Consumer offers to decrease the deal price;
  • Any participant offers to change deal duration (increase or decrease).

You may see proposed change requests in deal status (see 'sonmcli deal status' command).

Change request does not affect deal conditions untill approval by counterparty.

Counterparty may:

  • approve change request;
  • propose own change request;
  • cancel proposed (his own, or counterparty's) change request;
  • ignore proposed change request (the deal will be performed under previously agreed terms).

Usage:

sonmcli deal change-request [command]

Available Commands:

approve     Agree to change deal conditions with given change request
cancel      Decline given change request
create      Request changes for given deal

Agree to change deal conditions with given change request

Usage:

sonmcli deal change-request approve <req_id> [flags]

Decline given change requests

Usage:

sonmcli deal change-request cancel <req_id> [flags]

Request changes for given deal

Usage:

sonmcli deal change-request create <deal_id> [flags]

Examples:

sonmcli deal change-request create 123 --new-duration=10h --new-price=0.3USD/h

Flags:

--new-duration string   Propose new duration for a deal
--new-price string  Propose new price for a deal

Help about any command

Use flag -h or --help to get help about any command.

Open or generate Etherum keys

SONM CLI may generate new UTC/JSON keystore with this command if you just installed SONM coomponents. If you have several keystore files in your keystore folder, you may switch between them.

Usage:

sonmcli login [addr] [flags]

Manage master and workers addresses

Supplier should specify his Master ethereum address in Worker configuration file (/etc/sonm/worker-default.yaml). Master address is using for payment execution for a deal. One Supplier may have unlimited Worker nodes.

The relation "master" - "worker" is recorded in the blockchain. Worker checks the availability of a record in the blockchain at each start. If there is no entry, the vorker will create it. The resource owner must confirm the application of the vorker, using sonmcli master confirm <worker ether address> command. Supplier may manage (confirm, remove) workers with Master key.

Important: Worker will not start to place ASK orders to the SONM marketplace until master has confirmed this worker.

Usage:

sonmcli master [command]

Available Commands:

confirm       Confirm pending Worker's registration request
list          Show known worker's addresses
remove_master Remove self from specified master
remove_worker Remove registered worker

Confirm pending Worker's registration request

Usage:

sonmcli master confirm <worker_eth> [flags]

Show known worker's addresses

Usage:

sonmcli master list [master_eth] [flags]

Remove self from specified master

Usage:

sonmcli master remove_master <master_eth> [flags]

Remove registered worker

Usage:

sonmcli master remove_worker <worker_eth> [flags]

Manage orders

Buyer (Consumer) may create or cancel BID orders on SONM marketplace. Buyer and Supplier may see the list of they BID and ASK orders. Anyone may check the status of any specified order.

Usage:

sonmcli order [command]

Available Commands:

cancel      Cancel order on Marketplace
create      Place new Bid order on Marketplace
list        Show your active orders
purge       Remove all your orders from Marketplace
status      Show order stats

Cancel order on Marketplace

Usage:

sonmcli order cancel <order_id> [flags]

Place new Bid order on Marketplace

Buyer should create BID order specification to create new BID order on SONM marketplace (bid.yaml). BID specification example:

# spot deal (0h, supplier may close the deal at any moment), or forward deal duration (fixed time)

duration: 0h
price: 0.06 USD/h

# optional - restricts buying resources only from specified address

# counterparty: 0x8125721c2413d99a33e351e1f6bb4e56b6b61567

# optional - third-party blacklist, wich you want take to account (well known address you trust,
# for example - SONM auto-buyer, that buys resources for mining, and blacklists suppliers who
# can not provide the promised performance, and considered as dishonest (unfair) supplier.

# blacklist: 0x1124fCC307756f4077c5e8E09b948C1CA7123eC9

# identity level of the counterparty. Can be "anonymous", "registered", "identified" and "professional"

identity: anonymous

# optional, set tag for the task
tag: my-app

# benchmarks for needed resources, some are mandatory (cpu-cores), other may be omitted
resources:
  # network connection requirements

  network:
    overlay: false
    outbound: true
    incoming: false

  # benchmarks for needed resources, some are mandatory (cpu-cores), other may be omitted
  # all values are given in units, for example:
  # - ram, gpu memory, network bandwidth must be specified in bytes,
  # - gpu-eth-hashrate - in hashes per second

  benchmarks:
    ram-size: 512000000
    cpu-cores: 1
    cpu-sysbench-single: 500
    cpu-sysbench-multi: 500
    net-download: 1000000
    net-upload: 1000000
    gpu-count: 1
    gpu-mem: 3000000000
    gpu-eth-hashrate: 50000000
    storage-size: 512000000
    gpu-cash-hashrate: 120
    gpu-redshift: 50

Usage:

sonmcli order create <bid.yaml> [flags]

Show your active orders

Usage:

sonmcli order list [flags]

Flags:

--limit uint   Orders count to show (default 10)

Remove all your orders from Marketplace

Customer may quickly remove all own active BID orders from the market with this command.

Usage:

sonmcli order purge [flags]

Show order status

Usage:

sonmcli order status <order_id> [flags]

Manage profiles

Usage:

sonmcli profiles [command]

Available Commands:

remove-attr Remove attribute form your profile
status      Show profile details

Remove attribute form your profile

User has a permission to remove any attribute from own profile.

Usage:

sonmcli profiles remove-attr [addr] [flags]

Show profile details

Usage:

sonmcli profile status [addr] [flags]

Tasks management

The group of commands for task management. Buyer may use these commands to mamnage tasks on rented hardware.

Usage:

sonmcli task [command]

Available Commands:

join        Provide network specs for joining to specified task's specific network
list        Show active tasks
logs        Retrieve task logs
pull        Pull committed image from the completed task.
push        Push an image from the filesystem
start       Start task
status      Show task status
stop        Stop task

Provide network specs for joining to specified task's specific network

Usage:

sonmcli task join <deal_id> <task_id> <network_id> [flags]

Show active tasks

Usage:

sonmcli task list [deal_id] [flags]

Retrieve task logs

Usage:

sonmcli task logs <deal_id> <task_id> [flags]

Flags:

      --detailed       Show extra details provided to logs
      --follow         Stream logs continuously    
      --since string   Show logs since timestamp (e.g. 2013-01-02T13:23:37) or relative (e.g. 42m for 42 minutes)
      --source         Show stream (stderr or stdout) for each line of logs
      --tail string    Number of lines to show from the end of the logs (default "50")
      --ts             Show timestamp for each log line (default true)
      --type string    "stdout" or "stderr" or "both" (default "both")

Pull committed image from the completed task

Usage:

sonmcli task pull <deal_id> <task_id> [flags]

Flags:

--output string   file to output

Push an image from the filesystem

Usage:

sonmcli task push <deal_id> <archive_path> [flags]

Start task

Buyer should create task specification to run task on rented hardware (task.yaml). Task specification example:

# docker image settings, required section
container:
  # Image name to start on worker, required param.
  image: httpd:latest
  # Env variables that will be passed to container on start.
  env:
    param1: value1
    param2: value2
    param3: value3
  # Add ability to pull container back.
  commit_on_stop: true
#  networks:
#    - type: tinc
#      subnet: "10.20.30.0/24"
#  volumes:
#    cifs:
#      type: cifs
#      options:
#        share: samba-host.ru/share
#        username: username
#        password: password
#        security: ntlm
#        vers: 3.0
#  mounts:
#    - cifs:/mnt:rw
#    - cifs:/opt:rw
# # custom registry settings, optional section
# registry:
#   # if not empty, Worker will use given registry to pull an image from, optional param
#   server_address: registry.user.io
#   # registry username, optional param
#   username: name
#   # registry password, optional param
#   password: secret

Usage:

sonmcli task start <deal_id> <task.yaml> [flags]

Show task status

Usage:

sonmcli task status <deal_id> <task_id> [flags]

Stop task

Usage:

sonmcli task stop <deal_id> <task_id> [flags]

Manage tokens

Usage:

sonmcli token [command]

Available Commands:

allowance   Show current allowance dor marketplace on sidchain network
balance     Show SONM token balance (ERC20)
deposit     Transfer funds from masterchain to SONM blockchain
withdraw    Transfer funds from SONM blockchain to masterchain

Show current allowance dor marketplace on sidchain network

Show current allowance for marketplace smart contract on SONM blockchain.

Usage:

sonmcli token allowance [flags]

Show SONM token balance (ERC20)

Usage:

sonmcli token balance [flags]

Transfer funds from masterchain to SONM blockchain

Transfer specified amount of SNM tokens from masterchain to SONM blockchain.

Usage:

sonmcli token deposit <amount> [flags]

Transfer funds from SONM blockchain to masterchain

Transfer specified amount of SNM tokens from SONM blockchain to masterchain.

Usage:

sonmcli token withdraw <amount> [flags]

Show version

Usage:

sonmcli version [flags]

Worker management

Worker management for Supplier. Supplier may manage worker locally or with remote access with Master key or Admin key (specified in worker config /etc/sonm/worker-default.yaml).

Usage:

sonmcli worker [command]

Available Commands:

ask-plan    Operations with ask order plan
current     Show current worker's addr
devices     Show Worker's hardware
free-devices    Show Worker's hardware with remaining resources available for scheduling
maintenance Schedule worker maintenance
next-maintenance    Print next scheduled maintenance
status      Show worker status
switch      Switch current worker to specified addr
tasks       Show tasks running on Worker

Operations with ask order plan

The normal way for Supplier is to use auto-seller bot 'Optimus' to manage worker resources and place ASK orders to the market. But manual management for ask-plans is also allowed.

Usage:

sonmcli worker ask-plan [command]

Available Commands:

create      Create new plan
list        Show current ask plans
purge       Purge all exiting ask-plans on worker
remove      Remove plan by ID

Create new ask-plan

The normal way for Supplier is to use auto-seller bot 'Optimus' to manage worker resources and place ASK orders to the market. But manual management for ask-plans is also allowed.

Ask-plan example:

duration: 8h
price: 0.73 USD/h

# You may specify any public blacklist address (in addition to your own blacklist). Deal cannot be opened if counterparty is included to blacklist.
blacklist: 0x8125721c2413d99a33e351e1f6bb4e56b6b633fd

# optional - restricts selling resources only to specified address
# counterparty: 0x8125721c2413d99a33e351e1f6bb4e56b6b61567

# identity level of the counterparty. Can be "anonymous", "pseudonymous" and "identified"
identity: anonymous

resources:
  cpu:
    # Number of cores to assign for this plan, can be fractional
    cores: 1.5
  ram:
    size: 2GB
  storage:
    size: 512MB
  gpu:
    indexes: [3, 5]
  network:
    throughputin: 25 Mbit/s
    throughputout: 40 Mbit/s
    overlay: true
    outbound: true
    incoming: true

Usage:

sonmcli worker ask-plan create <ask_plan.yaml> [flags]

Show current ask plans

Usage:

sonmcli worker ask-plan list [flags]

Purge all exiting ask-plans on worker

Usage:

sonmcli worker ask-plan purge [flags]

Remove plan by ID

Usage:

sonmcli worker ask-plan remove <order_id> [flags]

Operation with worker benchmarks

Usage:

sonmcli worker benchmark [command]

Available Commands;

purge - Remove all benchmarks from cache to rebenchmark on next worker restart
remove - Remove specified benchmark from cache to rebenchmark on next worker restart

Remove all benchmarks from cache to rebenchmark on next worker restart

Usage:

sonmci worker benchmark purge [flags]

Remove specified benchmark from cache to rebenchmark on next worker restart

Usage:

sonmcli worker benchmark remove <id> [flags]

Show current worker's addr

Usage:

sonmcli worker current [flags]

Show Worker's hardware

Usage:

sonmcli worker devices [flags]

Show Worker's hardware with remaining resources available for scheduling

Usage:

sonmcli worker free_devices [flags]

Schedule worker maintanance

This command allows Supplier to schedule worker maintenance at certain time specified, or after expiration of time period specified.

Duration of all active ASK orders will be reduced to match maintenance time specified.

After the specified maintenance time has come, all spot deals will be closed automatically, active ASK orders will be removed from marketplace.

We strictly recommend to check for existing Forward deals when planning worker maintenance. Worker maintenance mode does not affect opened forward deals. If you will switch worker OFF when forwarding deal is active, it is highly probable that you will receive claim as unfair Supplier, and will be included in counterpart’s blacklist.

Usage:

sonmcli worker maintenance [flags]

Print next scheduled maintenance

Usage:

sonmcli worker next-maintenance [flags]

Show worker status

Usage:

sonmcli worker status [flags]

Switch to another Worker

You may see all available workers to manage with sonmcli master list + <your Master ethereum address (may be omitted if you use SONM Node with keystore containing your Masker key)>.

Usage:

sonmcli worker switch <eth_addr> [flags]

Show tasks running on Worker

Usage:

sonmcli worker tasks [flags]