Libra CLI

This guide describes how to use the Libra command line interface (CLI) client to interact with the Libra Blockchain. The CLI is invoked as an interactive shell. It provides basic commands to create accounts, mint coins, perform transfers, and query the blockchain. You can use the CLI client to interact with a validator node on the testnet, on a local Libra Blockchain, or on a remote blockchain by specifying the node's hostname.

Invocation

There are three ways to invoke the Libra CLI client.

Connect to the Testnet via the CLI Client

To connect to the testnet through the CLI, a convenience script can be used to invoke the CLI without needing to specify parameters. To invoke this, change to the libra directory and run:

./scripts/cli/start_cli_testnet.sh

Run a Local Libra Network and Spawn a CLI Client

To start a local Libra network and spawn a CLI client that connects to this local network, run:

cargo run -p libra_swarm -- -s

The -s option causes the CLI to be run after the local Libra network is launched. Note that this may take a few minutes to build and then start.

Run a CLI Client to Connect to Any Libra Network

To invoke the CLI client and configure it yourself, run:

cargo run -p client --bin client -- [OPTIONS] --host <host> --validator_set_file <validator_set_file>

Options

The options for running the CLI client command to connect to any Libra network are:

• -m | --faucet_key_file_path — Path to the generated key-pair for the faucet account. The faucet account can be used to mint coins. If not passed, a new key-pair will be generated for you and placed in a temporary directory. To manually generate a keypair, use generate_keypair: cargo run -p generate_keypair -- -o <output_file_path>.
• -f | --faucet_server — The host that operates a faucet service. If not passed, this will be derived from the host parameter.
• -a | —-host — The destination host for CLI to connect to.
• -p | -—port — The public port of the destination Libra Blockchain for the client to connect with, the default value is 30307.
• -n | --mnemonic_file — The file location from which to load the mnemonic word for user account address/key generation. If not passed, a new mnemonic file is generated in the current directory by libra_wallet.
• -s | --validator_set_file — File location from which to load config of trusted validators. It is used to verify validator signatures in validator query response. The file should at least include public key of all validators trusted by the client — which should typically be all validators on the network. To connect to testnet, use 'libra/scripts/cli/trusted_peers.config.toml'. Can be generated by libra-config for local testing: cargo run --bin libra-config but the preferred method is to simply use libra-swarm to run local networks.

Commands

Once started with any of the three commands previously mentioned, the following CLI commands are available:

major_command subcommand [options]

If you enter only the major command, it will show the help information for that command. Major commands can be any one of the following:

account | a — Account related operations. Subcommands include:

create | c — Create a random account with private/public key pair. Account information will be held in memory only. The created account will not be saved to chain.

   Usage:
    create|c

list | la — Print all accounts that were created or loaded.

 Usage:
    list|la

recover | r <file_path> — Recover all accounts that were written to a file via the account write command.

 Usage:
    recover|r <file_path>
 Arguments:
     file_path - File path from which to load mnemonic recover seed.  Must have been written via `account write`

write | w <file path> — Save Libra wallet mnemonic recovery seed to disk. This will allow accounts to be recovered via account recover.

 Usage:
    write|w <file_path>
 Arguments:
     file_path - File path at which to save the mnemonic recovery seed to disk.

<mint | m> | <mintb| mb> — Mint coins to the account. Suffix 'b' is for blocking. If blocking is specified (using suffix 'b'), CLI will query chain until the transaction is finalized/available. Same is true for other sub "blocking" commands.

  Usage:
    mint|mint|m|b <receiver_account_ref_id>|<receiver_account_address> <number_of_coins>
  Arguments:
      receiver_account_ref_id | receiver_account_address - The receiver account to mint the coins to.
            If the receiver account does not exist, it will be created first.
            Either receiver_account_address or receiver_account_ref_id (an internal index of
            the account in the CLI client) can be used to specify receiver account (identical to
            other commands). If gas is being charged, the account that sent this mint transaction
            (currently preloaded genesis account) pays for the gas.
      number_of_coins - The number of coins to be minted to the receiver account.

transfer | transferb | t | tb — Transfer coins from account to another. Suffix 'b' is for blocking.

Usage:
    transfer|transferb|t|tb <sender_account_address>|<sender_account_ref_id> <receiver_account_address>|<receiver_account_ref_id> <number_of_coins> [gas_unit_price (default=0)] [max_gas_amount (default 10000)]
Arguments:
    sender_account_address | sender_account_ref_id - The account from which this transfer transaction
        is sent. The sender account pays for the gas.
    receive_account_address | receiver_account_ref_id - The account to which this transaction sends coins.
        If the receiver account does not exist, it will be created first. The sender will pay for
        gas required for both account creation and coin transfer.
    number_of_coins - The number of coins transferred to receiver account.
    gas_unit_price - The unit price to pay for gas.
    max_gas_amount - Max units of gas user is willing to pay for this transaction.

query | q — Query data from destination chain. All query operations are blocking. Subcommands include:

balance | b — Get the current balance of an account

 Usage:
    balance | b <account_ref_id>|<account_address>
 Arguments:
     account_ref_id | account_address - The account to query balance for.

sequence | s — Get the current sequence number for an account.

  Usage:
    sequence | s <account_ref_id>|<account_address> [reset_sequence_number=true|false]
  Arguments:
      account_ref_id | account_address - The account to get current/latest sequence number.
      reset_sequence_number - If the sequence number known locally by the CLI differs from the
            value known on chain, this will reset the local sequence number to to on-chain
            value.  This is useful when a user encounters an invalid sequence number error.

account_state | as — Get the latest state for an account.

  Usage:
    account_state | as <account_ref_id>|<account_address>
  Arguments:
      account_ref_id | account_address - The account to query latest state.

txn_acc_seq | ts — Get the committed transaction by account and sequence number.

  Usage:
    txn_acc_seq | ts <account_ref_id>|<account_address> <sequence_number> <fetch_events=true|false>
  Arguments:
      account_ref_id | account_address - The account to query committed transaction.
      sequence_number - The sequence number of committed transaction.
      fetch_events - Set to true to fetch events emitted by this transaction.

txn_range | tr — Get the committed transaction by range

  Usage:
    txn_range | tr <start_version> <limit> <fetch_events=true|false>
  Arguments:
      start_version - The version to query the transaction from.
      limit - The maximum number of transactions to query.
      fetch_events - Set to true to fetch events emitted by each transaction.

event | ev — Get event by account and path.

  Usage:
    event | ev <account_ref_id>|<account_address> <sent|received> <start_sequence_number> <ascending=true|false> <limit>
  Arguments:
      account_ref_id | account_address - The account to query events from.
      sent | received - Fetch sent or received events for this account.
            Note that this will later evolve into selecting any event path.
      start_sequence_number - The sequence number of events to query starting from.
      ascending - The direction of query from start_sequence_number.
      limit - The maximum number of events to query.

quit | q! — Exits the CLI. No subcommand is required.

help | h — Prints help. No subcommand is required.

Account Creation/Minting (Faucet) for Testnet

Account creation provided by the CLI generates a local keypair, but nothing is created on the blockchain. To create an account on the blockchain:

• Transfer coins to the address you wish to create. If the recipient account does not exist, the recipient account will be created first and then coins will be transferred. The sender pays for both account creation and transfer.
• Send a mint transaction to mint coins to an account. If the account does not exist, the account will be created first and the coins wil be minted later. Unlike other transactions, a nonexistent account itself can request a mint transaction. For the testnet, there is no explicit limit on how many coins an account can mint. It's designed to allow the users to create coins to experiment on the testnet.