Skip to main content

Command Line Interface (CLI)

BNB CLI is one of several ways to interact with BNB Beacon Chain.

BNB CLI can be used as a local wallet, you can manage your keys via Beacon CLI. You can add a new key or restore your key from mnemonic words. And you can list your keys and show specified key info.

With BNB CLI, you can send transactions to BNB Beacon Chain, like placing an order, transferring token, issuing token and so on. Actually you can do almost everything you can do with BNB Beacon Chain web wallet. What is more, you can propose to list trading pairs and join chain governance.

In addition, you can do some simple queries through CLI. For example, you can query your account's balance, transaction detail by transaction hash and etc.

Where can I download the BNB CLI?

You can download BNB CLI releases here:

You can choose to download the version for testnet (tbnbcli) or mainnet (bnblci).

CLI installation

Once you have downloaded the binary for your platform, you may drop it into any folder you like. Open a terminal window or cmd.exe in that folder, and then follow the examples on the documentation site.

For mainnet:

$  ./bnbcli

On Windows you would most likely use this instead:

C:\> bnbcli.exe

For testnet:

$  ./tbnbcli

On Windows you would most likely use this instead:

C:\> tbnbcli.exe

Where to connect

You can manage you keys locally without connecting to any node. But if you want to interact with BNB Beacon Chain, you need to connect to one of BNB Beacon Chain full nodes.

You can run your own full node, which may automatically connect to BNB Beacon Chain, and you can run your CLI there with your own full node. In the mean time, you can connect to any full nodes provided by other people.

You could query this API for for a list of full node on mainnet:

For testnet, visit

Full nodes will be denoted as the format of ip:port, you could use access_addr as your peer to get connected, such as

Please note that there are two types of nodes that offer RPC services. Some support TLS and others don't.

Which Chain-ID to use

chain-id is an important field to fill for every transaction sent from bnbcli. The chain-id for mainnet is Binance-Chain-Tigris, and is Binance-Chain-Ganges for testnet. Please choose the correct one in your case.

Which Private Key To Use

There are two ways for you to sign transaction:

  • Use Local Keystore File

This is the default way to sign transactions with bnbcli. It will use the encrypted keystore files saved at bnbcli home. You need to specify which key to decrypt with --from.

  • Use Private Key in Hardware Wallet

First, you must add --ledger when creating a new address. For example,

bnbcli keys add test --ledger --index 0 --account 0

Then, the private key file in ledger will be used to generate a new address.

You could also specify --account and --index to generate more addresses. After the generation, you could use Ledger for signing.

When you use the address to sign transactions, bnbcli will send transactions to Ledger and get signatures. Then bnbcli build the signed transactions and boardcast them to full nodes.

Key manager

Here we support two types of key: local key and leder key

Local key

  • Create a local key
bnbcli keys add test_key

The newly created local key will be encrypted and saved to the local keystore.

  • Sign transaction with a local key
bnbcli send --chain-id=<chain-id> --from=test_key --amount=100:BNB --to=<address>

For instance, if you want to send a token transfer transaction, you can use the above command. The flag --from is used to specify which key should be used to sign the transaction.

Ledger key

  • Create a local key

Before creating a new ledger key, make sure you have performed these steps:

  1. Ledger device is installed, binance ledger app and the version should be later or equal to v1.1.3.
  2. Connect your ledger device to your machine and input pin code to unlock it.
  3. Open the binance ledger app on your ledger device.
bnbcli keys add test_ledger_key --ledger

Execute the above command to create a ledger key. The private key is only stored in your ledger device. And your local key store will save the corresponding publick key and address.

bnbcli keys add test_ledger_key_new --ledger --index 0 --account 0

You can also specify --account and --index to generate more keys.

  • Sign transaction with a ledger key

Taking transfer transaction for example, please follow these steps:

  1. Execute command in your console:
bnbcli send --chain-id=<chain-id> --from=test_ledger_key --amount=100:BNB --to=<address>
  1. Your console will print some message like this:
Please confirm if address displayed on ledger is identical to bnb15339dcwlq5nza4atfmqxfx6mhamywz35evruva (yes/no)?
  1. User can click confirm button on ledger device and input yes to continue following steps.
  2. Then user can preview the transaction data on ledger screen.
  3. After going through all transaction data, user can select sign transaction or reject.
  4. After user selects sign transaction, bnbcli will get the signature and broadcast the signed transaction to blockchain nodes.

How to use

When you have downloaded BNB Chain CLI, you can use help subcommand to see all the available commands:

$  ./bnbcli help
BNBChain light-client

bnbcli [command]

Available Commands:
init Initialize light client
status Query remote node for status

txs Search for all transactions that match the given tags.
tx Matches this txhash over all committed blocks

account Query account balance
send Create and sign a send tx

api-server Start the API server daemon
keys Add or view local private keys

version Print the app version
token issue or view tokens
dex dex commands
gov gov commands
help Help about any command

-e, --encoding string Binary encoding (hex|b64|btc) (default "hex")
-h, --help help for bnbcli
--home string directory for config and data (default "/root/.bnbcli")
-o, --output string Output format (text|json) (default "text")
--trace print out full stack trace on errors

Use "bnbcli [command] --help" for more information about a command.

Note:there is one special flag --trust-node of most subcommands, if not enabled which is by default the CLI will take an extra 2-4 seconds to verify blockchain proof at current height. You can enable that flag if the peer is trustful so that most commands will accomplish in 500 milliseconds. If your node cannot prove the transaction, there will be the following notice:

Create verifier failed: Commit: Response error: RPC error -32603 - Internal error: runtime error: invalid memory address or nil pointer dereference
Please check network connection and verify the address of the node to connect to

To solve this issue, you need to set --trust-node to true

CLI Reference

For detailed usage, you can refer to:

Use CLI for Different Blockchains

bnbcli will save data about validatorset changes at home of bnbcli. If you want to use bnbcli for different blockchains, for example, you want to change from testnet to mainnet, the data will be stale. In order to switch between blockchains, you need clean the data folder with rm -rf ~/.bnbcli/.bnblite/ or create a new home folder for bnbcli with --home flag. If you forget to specify a different home folder path, then you will not be able to make queries with bnbcli.

The same logic applies to tbnbcli.