Command-line interface

Command-line interface

The command-line interface (CLI) is a straightforward way to experiment with the Entropy network and explore common workflows.

Install

Follow these steps to install Entropy globally using NPM:

  1. The CLI requires Node version 20 or higher to run:

    node --version
    v23.1.0
    ℹ️
    Consider using Node Version Manager (NVM) to keep your Node installation organized. NVM also makes it trivial to switch between Node versions when necessary.
  2. Install the Entropy CLI globally using NPM:

    npm install --global @entropyxyz/cli
  3. You can now run the CLI from anywhere using entropy:

    entropy
    Usage: entropy [options] [command]
    
    CLI interface for interacting with entropy.xyz. Running without commands starts an interactive ui
    
    Options:
      -e, --endpoint <endpoint>                           Runs entropy with the given endpoint and ignores
                                                          network endpoints in config. Can also be given a
                                                          stored endpoint name from config eg: `entropy
    
                                                          --endpoint test-net`. (default:
                                                          "ws://testnet.entropy.xyz:9944/", env: ENDPOINT)
      -h, --help                                          display help for command
    
    Commands:
      list|ls                                             List all accounts. Output is JSON of form [{ name,
                                                          address, data }]
    
      balance [options] <address>                         Get the balance of an Entropy account. Output is a
    
                                                          number
      transfer [options] <source> <destination> <amount>  Transfer funds between two Entropy accounts.
      sign [options] <address> <message>                  Sign a message using the Entropy network. Output is
                                                          a signature (string)
  4. You can also interact with the CLI through the TUI by adding tui: «««< HEAD

    entropy tui
    ? Select Action (Use arrow keys)
    
    ❯ Manage Accounts
      Balance
      Register
      Sign
      Transfer
      Deploy Program
      User Programs
      Exit

Programmatic CLI

You can interact with Entropy quickly by giving single-line commands to the entropy executable.

Usage: entropy [options] [command]

CLI interface for interacting with entropy.xyz.

Options:
  -v, --version                              Displays the current running version of Entropy CLI.
  -cv, --core-version                        Displays the current running version of the Entropy Protocol
  -h, --help                                 display help for command

Commands:
  tui [options]                              Text-based User Interface (interactive)
  account                                    Commands to work with accounts on the Entropy Network
  sign [options] <msg>                       Sign a message using the Entropy network. Output is a JSON { verifyingKey, signature }
  balance [options] <account>                Command to retrieive the balance of an account on the Entropy Network
  transfer [options] <destination> <amount>  Transfer funds between two Entropy accounts.
  program                                    Commands for working with programs deployed to the Entropy Network

tui

Usage: entropy tui [options]

Text-based User Interface (interactive)

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

account

Usage: entropy account [options] [command]

Commands to work with accounts on the Entropy Network

Options:
  -h, --help                      display help for command

Commands:
  create|new [options] <name>     Create a new entropy account from scratch. Output is JSON of form {name, address}
  import [options] <name> <seed>  Import an existing entropy account from seed. Output is JSON of form {name, address}
  list|ls                         List all accounts. Output is JSON of form [{ name, address, verifyingKeys }]
  register [options]              Register an entropy account with a program
  help [command]                  display help for command

create

Usage: entropy account create|new [options] <name>

Create a new entropy account from scratch. Output is JSON of form {name, address}

Arguments:
  name        A user friendly name for your new account.

Options:
  --path      Derivation path
  -h, --help  display help for command

import

Usage: entropy account import [options] <name> <seed>

Import an existing entropy account from seed. Output is JSON of form {name, address}

Arguments:
  name        A user friendly name for your new account.
  seed        The seed for the account you are importing

Options:
  --path      Derivation path
  -h, --help  display help for command

list

Usage: entropy account list|ls [options]

List all accounts. Output is JSON of form [{ name, address, verifyingKeys }]

Options:
  -h, --help  display help for command

register

Usage: entropy account register [options]

Register an entropy account with a program

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

sign

Usage: entropy sign [options] <msg>

Sign a message using the Entropy network. Output is a JSON { verifyingKey, signature }

Arguments:
  msg                           Message you would like to sign (string)

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

balance

Usage: entropy balance [options] <account>

Command to retrieive the balance of an account on the Entropy Network

Arguments:
  account               The address an account address whose balance you want to query. Can also be the human-readable name of one of your accounts

Options:
  -e, --endpoint <url>  Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help            display help for command

transfer

Usage: entropy transfer [options] <destination> <amount>

Transfer funds between two Entropy accounts.

Arguments:
  destination                   Account address funds will be sent to
  amount                        Amount of funds to be moved (in "tokens")

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

program

Usage: entropy program [options] [command]

Commands for working with programs deployed to the Entropy Network

Options:
  -h, --help                                                               display help for command

Commands:
  deploy [options] <bytecode> <configurationSchema> <auxillaryDataSchema>  Deploys a program to the Entropy network, returning a program pointer. Requires funds.
  get [options] <programPointer>                                           Get a program interface by it's pointer.
  listDeployed [options]                                                   Get a list of all programs the current account has deployed
  add [options] <programPointer> [programConfigPath]                       Add a program to the current account
  remove|rm [options] <programPointer>                                     Remove a program from an account (specified by a verifyingKey)
  list|ls [options] <verifyingKey>                                         List all the programs (an associated config) added to a particular verifyingKey.
  help [command]                                                           display help for command

deploy

Usage: entropy program deploy [options] <bytecode> <configurationSchema> <auxillaryDataSchema>

Deploys a program to the Entropy network, returning a program pointer. Requires
funds.

Arguments:
  bytecode                      The path to your program bytecode. Must be a .wasm file.
  configurationSchema           The path to the JSON Schema for validating configurations passed in by users installing this program. Must be a .json file.
  auxillaryDataSchema           The path to the JSON Schema for validating auxillary data passed to the program on calls to "sign". Must be a .json file.

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

get

Usage: entropy program get [options] <programPointer>

Get a program interface by it's pointer.

Arguments:
  programPointer                The pointer for the program interface.

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

listDeployed

Usage: entropy program listDeployed [options]

Get a list of all programs the current account has deployed

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

add

Usage: entropy program add [options] <programPointer> [programConfigPath]

Add a program to the current account

Arguments:
  programPointer                The pointer for the program interface.
  programConfigPath             The path to the config to apply to the program.
                                Must be a .json file

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -k, --verifying-key <key>     The verifying key to perform this function
                                with.
  -h, --help                    display help for command

remove

Usage: entropy program remove|rm [options] <programPointer>

Remove a program from an account (specified by a verifyingKey)

Arguments:
  programPointer                The pointer for the program you want to remove.

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -k, --verifying-key <key>     The verifying key to perform this function
                                with.
  -p, --program-mod-key <key>   The programModKey to perform this function
                                with.
  -h, --help                    display help for command

list

Usage: entropy program list|ls [options] <verifyingKey>

List all the programs (an associated config) added to a particular
verifyingKey.

Arguments:
  verifyingKey                  The verifyingKey being queried.

Options:
  -a, --account <name|address>  Sets the account for the session. Defaults to the last set account (or the first account if one has not been set before). (default: "", env: ENTROPY_ACCOUNT)
  -e, --endpoint <url>          Runs entropy with the given endpoint and ignores network endpoints in config. Can also be given a stored endpoint name from config eg: `entropy --endpoint test-net`. (default: "wss://testnet.entropy.xyz/", env: ENTROPY_ENDPOINT)
  -h, --help                    display help for command

Text-based user interface

  @@@@@@@@@@ @@@@@@@@@@ @@@@@   @@@@@@@@@@@ @@@@@@@@@ @@@@@@@@@@ @@@@@ @@@@@
  @@@@@@@@@@ @@@@@@@@@@ @@@@@   @@@@@@@@@@@ @@@@@@@@@ @@@@@@@@@@ @@@@@ @@@@@
  @@@@@@@@@@ @@@@@@@@@@ @@@@@@@ @@@@@@@@@@@ @@@@@@@@@ @@@@@@@@@@ @@@@@ @@@@@
  @@@@@ @@@@ @@@@@ @@@@ @@@@@@@ @@@@@ @@@@@ @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@ @@@@ @@@@@ @@@@ @@@@@   @@@@@ @@@@@ @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@ @@@@ @@@@@ @@@@ @@@@@   @@@@@ @@@@@ @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@@@@@@ @@@@@ @@@@ @@@@@   @@@@@       @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@@@@@@ @@@@@ @@@@ @@@@@   @@@@@       @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@      @@@@@ @@@@ @@@@@   @@@@@       @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@ @@@@ @@@@@ @@@@ @@@@@   @@@@@       @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@ @@@@ @@@@@ @@@@ @@@@@   @@@@@       @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@ @@@@ @@@@@ @@@@ @@@@@   @@@@@       @@@@ @@@@ @@@@@ @@@@ @@@@@ @@@@@
  @@@@@@@@@@ @@@@@ @@@@ @@@@@@@ @@@@@       @@@@@@@@@ @@@@@@@@@@ @@@@@@@@@@@
  @@@@@@@@@@ @@@@@ @@@@ @@@@@@@ @@@@@       @@@@@@@@@ @@@@@@@@@@ @@@@@@@@@@@
                                                      @@@@@@            TEST
                                                      @@@@@@            *NET
                                                      @@@@@@     ENTROPY-CLI
                                                      @@@@@@     COREv0.3.0

? Select Action (Use arrow keys)
❯ Manage Accounts
  Entropy Faucet
  Balance
  Register
  Sign
  Transfer
  Deploy Program
  User Programs
  Exit

The following functions are available within the CLI using the text-based user interface (TUI). To start the TUI, simply enter entropy tui without any arguments into your terminal:

entropy tui
? Select Action (Use arrow keys)

❯ Manage Accounts
  Balance
  Register
  Sign
  Transfer
  Deploy Program
  User Programs
  Exit

Manage Accounts

Create, import, and list your accounts.

❯ Create/Import Account
  Select Account
  List Accounts
  Exit to Main Menu

Entropy Faucet

Get test funds to spend on the testnet.

Account: 5F3xmKa3WRkoHR4o6XjFQaWF2EskhtSh4ST5wY5cfsD9JYbC has been successfully funded with 20,000,000,000 BITS

Balance

Get the balance of an account. You can select any of the accounts stored locally or enter an Entropy address.

? Select Action Balance
Address 5Dcps2RdXPQfiJBxxDnrF8iDzDHcnZC8rb5mcJ3xicqzhYbv has a balance of: 382000000000000 bits
? Return to main menu? (Y/n)

Register

Register a locally stored account with the Entropy network.

Attempting to register the address: 5Dcps2RdXPQfiJBxxDnrF8iDzDHcnZC8rb5mcJ3xicqzhYbv
Your address 5Dcps2RdXPQfiJBxxDnrF8iDzDHcnZC8rb5mcJ3xicqzhYbv has been successfully registered.

The selected account must have available funds. Each registration costs about 400000000 bits.

Sign

Sign a message using a registered account.

? Choose account: (Use arrow keys)
  aragon (5FTwtSAjnKFybzkAKvyEo7owikXcHXmwzN7MzjwDNKEbjkub)
> charlie (5Ck5SLSHYac6WFt5UZRSsdJjwmpSZq85fd5TRNAdZQVzEAPT)
  Other

Transfer

Transfer funds from a locally stored account to any other valid Entropy address.

? Select Action Transfer
? Input amount to transfer: 12345
? Input recipient's address: 5G92hBs4UfZpVFYtBmmN3UqPTzGgotq7PSA3XfBMALfvWDUb
Transferring Funds |++++___________________| 22%

The amount to transfer value is in whole units, not bits. So transferring 1 would equal 10000000000 bits.

Deploy Program

Deploy a program from a locally stored account.

? Select Action Deploy Program
? Select your action: (Use arrow keys)
> Deploy
  Get Program Pointers

  Exit

User Programs

View all programs deployed to the network from locally stored accounts.

? Select Action User Programs
? What would you like to do? (Use arrow keys)
> View My Programs
  Add a Program to My List
  Remove a Program from My List
  Check if Program Exists
  Exit to Main Menu

Configuration

The CLI uses a configuration file to set and store basic information. This CLI uses env-paths to determine where configurations files should be stored:

  • Arch: ~/.config/entropy-cryptography/entropy-cli.json
  • MacOS: /Library/Preferences/entropy-cryptography/entropy-cli.json
  • Ubuntu: ~/.config/entropy-cryptography/entropy-cli.json
  • Windows: C:\Users\<USERNAME>\AppData\Roaming\entropy-cryptography\Config\entropy-cli.json

Config file contents

This configuration file contains:

DescriptionName in configuration file
Account informationaccounts: [...]
Which account is currently selectedselectAccount
Endpoints that you are connected toendpoints: {...}
Configuration versionmigration-version
The config file contains your unencrypted private key.

Deleting your config

The config file gets generated the first time that you start the CLI. If you somehow break your config, you can delete your existing config and start the CLI – it will generate a new base config.

Logs

Similar to the configuration file, log files for this CLI can be found in the default env-paths locations:

  • Arch: ~/.local/state/entropy-cryptography/
  • MacOS: /Library/Logs/entropy-cryptography/
  • Ubuntu: ~/.local/state/entropy-cryptography/
  • Windows: C:\Users\<USERNAME>\AppData\Local\entropy-cryptography\Log

Log file contents

There are three types of log file:

  • Debug: Contains detailed technical information useful for troubleshooting during software development and maintenance.
  • Error: Records specific software failures, including the time, severity, and context of each error.
  • Info: Tracks general system events, providing a high-level overview of the application’s behaviour.

Troubleshooting

Here are some common problems you could encounter and how to get around them.

How do I quit the CLI?

Press CTRL + c at any point to exit the CLI program, even if you’re within a function:

? Select Action Transfer
? Input amount to transfer: 1000
? Input recipient's address:        <----- Pressed `CTRL` + `c` here.
error Command failed with exit code 130.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
user@computer: $

ERR::: RpcError: 1010: Invalid Transaction: Inability to pay some fees , e.g. account balance too low

This likely means that you don’t have enough funds in the selected account to complete that function. Double-check that you’ve selected the correct account and that the account has enough funds in it. If you need more test funds, head over to the faucet for more.

CLI crashes when registering

You may encounter the following error when registering:

2024-06-05 00:11:42        REGISTRY: Unknown signed extensions ValidateConfirmRegistered found, treating them as no-effect
2024-06-05 00:11:42        API/INIT: RPC methods not decorated: chainSpec_v1_chainName, chainSpec_v1_genesisHash, chainSpec_v1_properties
Attempting to register the address: 5Dcps2RdXPQfiJBxxDnrF8iDzDHcnZC8rb5mcJ3xicqzhYbv
/root/cli/src/config/index.ts:21
  return JSON.parse(configBuffer.toString())
              ^
SyntaxError: Unexpected end of JSON input
    at JSON.parse (<anonymous>)
    at Object.get (/root/cli/src/config/index.ts:21:15)

    at async EventEmitter.<anonymous> (/root/cli/src/common/initializeEntropy.ts:102:23)

This is a bug that the Entropy team are aware of, and are working on a fix. In the meantime, restart the CLI and try to register that account again. If it keep failing, please raise an issue in the Entropy CLI repository.

How do I enter the text-based user interface?

Install the entropy executable and enter entropy from the command line without any arguments.