CLI reference
This guide describes how to use the Diem command line interface (CLI) client to interact with the Diem Blockchain’s testnet.
The CLI is invoked as an interactive shell. It provides basic commands to simulate the creation of accounts, the minting of Diem Coins, performing transfers, and querying the blockchain. You can use the CLI client to interact with a validator node in different types of networks such as testnet, a local test validator network, or on a remote blockchain by specifying the node's hostname.
Invoke the Diem CLI client#
There are two ways to invoke the Diem CLI client:
- Connect to testnet via the CLI client
- Run a CLI client to connect to any Diem network
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 diem directory and run:
./scripts/cli/start_cli_testnet.shRun a CLI Client to Connect to Any Diem Network#
To invoke the CLI client and configure it yourself, run:
cargo run -p cli --bin cli -- [OPTIONS] --host <host> --validator_set_file <validator_set_file>Options#
The options for running the CLI client command to connect to any Diem network are:
| Command | Description |
|---|---|
| `-c | --chain-id` |
| `-m | --faucet_key_file_path` |
| `-f | --faucet-url` |
| `-u | —-url` |
| `-n | --mnemonic_file` |
| `-r | --sync` |
--waypoint | If set, the client will use the waypoint parameter for its initial LedgerInfo verification. |
--waypoint_url | The URL to retrieve the waypoint from, if the waypoint parameter is not passed. |
--verbose | If set, the client will produce verbose output. |
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 the chain. Returns reference ID to use in other operations.
Usage: create|c list | la — Print all accounts that were created or loaded.
Usage: list|la recover | r — 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 — Save Diem 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. Creates an account at the recipient address if one does not already exist. 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> <currency_code> [use_base_units (default=false)] 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 (as in 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. currency_code - Which currency to mint. For example, `Coin1`.<addc | ac> | <addcb | acb> — Add specified currency to the account. Suffix 'b' is for blocking.
Usage: addc|addcb|ac|acb <account_address> <currency_code> Arguments: account_address - The account to add the currency to. currency_code - Which currency to add. For example, `Coin2`.---<transfer | t> | <transferb | tb> — Transfer coins from one 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> <currency_code> [gas_unit_price_in_micro_diems (default=0)] [max_gas_amount_in_micro_diems (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. currency_code - Which currency to transfer. For example, `Coin1`. gas_unit_price_in_micro_diems - The unit price to pay for gas. max_gas_amount_in_micro_diems - 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, and reset current sequence number in CLI (optional, default is false).
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 transactions by version range. Optionally also fetch events emitted by these transactions.
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 events by account and event type (sent|received).
Usage: event|ev <account_ref_id>|<account_address> <sent|received> <start_sequence_number> <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. limit - The maximum number of events to query.account_resources | ar — Get the latest annotated resources in an account.
Usage: account_resources|ar <account_ref_id>|<account_address> Arguments: account_ref_id|account_address - The account to query resources from.---dev | d — Operations related to Move transaction scripts and modules.#
**Note:** This command can only be used on a local network, it cannot be used on testnet.
Subcommands include:
compile | c — Compile a Move program.
Usage: compile|c <sender_account_address>|<sender_account_ref_id> <file_path> <dependency_source_files...> Arguments: sender_account_address|sender_account_ref_id - Address of the sender account|Local index of the sender account. file_path - Path to the source Move program dependency_source_files - Paths to any additional Move source files or directories of source files that the current file depends uponpublish | p — Publish a Move module on testnet.
Usage: publish|p <sender_account_address>|<sender_account_ref_id> <compiled_module_path> Arguments: sender_account_address|sender_account_ref_id - Address of the sender account|Local index of the sender account compiled_module_path - Path to the compiled module.execute | e — Execute custom Move transaction script.
Usage: execute|e <sender_account_address>|<sender_account_ref_id> <compiled_module_path> [parameters] Arguments: sender_account_address|sender_account_ref_id - Address of sender account|Local index of the sender account. compiled_module_path - Path to the compiled transaction script. parameters - Arguments expected by the transaction script.upgrade_stdlib | u — Upgrade the move stdlib used for the blockchain.
Usage: upgrade_stdlib|ugen_waypoint | g — Generate a waypoint for the latest epoch change LedgerInfo.
Usage: gen_waypoint|gchange_diem_version | v — Change the diem_version stored on chain.
Usage: change_diem_version|v <new_diem_version> Arguments: new_diem_version - New major version for the VM, must be strictly incrementing.enable_custom_script | s — Allow executing arbitrary script in the network. This disables script hash verification.
Usage: enable_custom_script|sadd_to_script_allow_list | a — Add a script hash to the allow list. This enables script hash verification.
Usage: add_to_script_allow_list|a <hash> Arguments: hash - Hash of the custom script to allow.---info | i — Print CLI config and client internal information.---
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 testnet blockchain. To create an account on tesnet:
- Transfer fake Diem Coins to the address you wish to create. If the recipient account does not exist, you must create the recipient account first, and then add the specific currency into the account in order for it to receive fake Diem Coins. The sender pays a transaction fee (gas) for both account creation and transfer.
- Send a mint transaction to simulate the minting of Diem Coins to an account. If the account does not exist, the account will be created first and the fake Diem Coins will be minted later. Unlike other transactions, a nonexistent account itself can request a simulated mint transaction.