1. Installing and Starting the CLI
The Koinos Command Line Interface (CLI) is a comprehensive command line tool for interacting with the Koinos Blockchain. You can download the latest release from GitHub. After downloading, you can start the CLI with the binary included in the archive.
For instance, if you downloaded the CLI to your Downloads directory and it’s named
koinos-cli, you can start it by opening a terminal and running:
cd Downloads ./koinos-cli
2. Basic Usage of the CLI
When running the wallet, it will start in interactive mode. You can press tab or type
list to see a list of possible commands. The
help <command-name> command will show a help message for the given command.
For example, if you want to know what the
transfer command does, you can type:
Some commands require a node RPC endpoint. This can be specified either when starting the CLI with
--rpc command line switch, or with the
connect command from within the CLI. Both take an endpoint URL.
Here is an example of launching from the command line with an RPC:
koinos-cli --rpc https://api.koinos.io/
And here is an example of the
You can use the public RPC server for testing at this address: https://api.koinos.io/
3. Wallet Creation & Management
To create a new wallet, use the command
create <filename> <password>. The new wallet will then be created in the given file, and automatically opened.
create my.wallet password1234
This will create a new wallet file named
my.wallet with the password
To open a previously created wallet, use the command
open <filename> <password>.
open my.wallet password1234
This will open the wallet file named
my.wallet using the password
To import an existing Wallet Import Format (WIF) private key, use the commands
import <wif> <filename> <password>.
import 5KPJcpkw7GBtxjNrzroYgVwjR8CnTwbPrybuwfb8ff1Hw4GcqB5 imported.wallet password1234
This will import the private key into a new wallet file named
imported.wallet with the password
To close the open wallet, simply use the
4. Other Useful Commands
To check the balance of a given public address, use the command
For example, to check the balance of the address
1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM, you would type:
To transfer tKOIN from the currently open wallet, use the command
transfer <amount> <address>.
For example, to transfer 10 tKOIN to the address
1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM, you would type:
transfer 10 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM
5. Smart Contract Management
To upload a smart contract, use the command
upload <filename>. The file given should be a compiled wasm smart contract. The contract id will be the public address of the currently open wallet.
This will upload the smart contract contained in the file
To interact with a smart contract, first register its ABI file with the command
register <name> <address> <abi-filename> using the contract’s address and a name of your choosing.
register koin 15im92XgZiV39tcKMhMGtDYhJjXPMjUu8r abi/koin.abi
This will register the ABI file
koin.abi for the smart contract at address
15im92XgZiV39tcKMhMGtDYhJjXPMjUu8r under the name
Its methods will then be added to the list of available commands in the CLI.
This will check the balance of the address
1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM in the
koin smart contract.
6. Transaction Sessions
Sometimes it is important to ensure multiple operations are included in the same block in a specific order. To accomplish this with the CLI, you use a session.
To begin a session, use the command
session begin. Any command that interacts with the chain will now be added to the current session.
To view the current session, use
To cancel the current session, use
When you are done adding commands to the session,
session submit will send the attached commands as a single transaction to the blockchain.
session begin transfer 1.0 1BLUi4ogqptnyBnSuKFyWMxEyVJzxiZWhM upload token.wasm transfer 25.0 15Pb7o5GFBB56njFNvU2fAfa9Mm7rmsJH1 session view session submit
This will start a session, add a transfer of 1.0 tKOIN, an upload of a smart contract, and another transfer of 25.0 tKOIN to the session, view the session, and then submit the session as a single transaction.
7. Non-Interactive Mode
Commands can be executed without using interactive mode. The
--execute command-line parameter takes a semicolon-separated list of commands, executes them, then returns to the terminal.
For example, to check the balance of an address and then quit, you could run:
koinos-cli --execute "balance 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM; quit"
8. Exiting the CLI
To quit the CLI, simply use the
9. Checking Connection Status
If there is a red symbol to the left of the prompt, it indicates that you are not connected to an RPC endpoint. To connect, use
10. Environment Variables
Any of the commands which take a password may be called with it omitted. In this case, it will use the value in the
WALLET_PASS environment variable /
.env file. For example, if you have set the
WALLET_PASS environment variable to
password1234, you can create a wallet without specifying the password:
11. Smart Contract Interaction
Once a smart contract is registered, its methods will be added to the list of available commands in the CLI. You can use these commands to interact with the smart contract.
For example, to check the balance of an address in a registered smart contract, you could use:
To transfer tokens from a registered smart contract, you could use:
koin.transfer 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM 13daTg586CnrVjKRjGwBtBWH6eda99A7bw 100000000
And to check the balance of the receiving address after the transfer, you could use:
12. Checking Node Status
To check the status of your node, use the
This will display information about the node’s current block height, network connections, and other vital statistics.
13. Checking Transaction Status
To check the status of a transaction, use the
transaction_status <transaction_id> command:
1234567890abcdef with the ID of the transaction you want to check. This will display information about the transaction, such as whether it has been included in a block.
14. Checking Block Information
To check the information of a block, use the
block_info <block_number> command:
12345 with the number of the block you want to check. This will display information about the block, such as its hash, the number of transactions it contains, and its timestamp.
15. Checking Account Information
To check the information of an account, use the
account_info <account_address> command:
1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM with the address of the account you want to check. This will display information about the account, such as its balance and the number of transactions it has made.
16. Checking Contract Information
To check the information of a contract, use the
contract_info <contract_address> command:
15im92XgZiV39tcKMhMGtDYhJjXPMjUu8r with the address of the contract you want to check. This will display information about the contract, such as its code and the number of transactions it has processed.
17. Sending Raw Transactions
To send a raw transaction, use the
send_raw_transaction <transaction_data> command:
0102030405060708090a0b0c0d0e0f with the raw data of the transaction you want to send. This is an advanced feature and should be used with caution.
18. Broadcasting Transactions
To broadcast a transaction to the network, use the
broadcast_transaction <transaction_data> command:
0102030405060708090a0b0c0d0e0f with the raw data of the transaction you want to broadcast. This will send the transaction to all connected nodes in the network.
19. Checking Network Connections
To check the network connections of your node, use the
This will display a list of all nodes your node is currently connected to, along with information about each connection.
20. Disconnecting from a Node
To disconnect from a node, use the
disconnect <node_address> command:
192.168.1.1 with the address of the node you want to disconnect from. This will close the
connection to that node.
21. Connecting to a Node
To connect to a node, use the
connect <node_address> command:
192.168.1.1 with the address of the node you want to connect to. This will establish a new connection to that node.
22. Checking Node Configuration
To check the configuration of your node, use the
This will display the current configuration of your node, including network settings, database settings, and other configuration options.
23. Updating Node Configuration
To update the configuration of your node, use the
config_update <config_option> <new_value> command:
config_update max_connections 50
max_connections with the configuration option you want to update, and
50 with the new value for that option. This will update the configuration of your node and apply the new settings.
24. Checking Node Logs
To check the logs of your node, use the
This will display the most recent logs from your node, including information about transactions, blocks, and network connections.
25. Checking Node Version
To check the version of your node, use the
This will display the version number of your node, along with other information about the build.
26. Checking Node Uptime
To check the uptime of your node, use the
This will display the amount of time your node has been running since it was last started.
27. Checking Node Peers
To check the peers of your node, use the
This will display a list of all nodes your node is currently peered with, along with information about each peer.
28. Checking Node Performance
To check the performance of your node, use the
This will display performance metrics for your node, including CPU usage, memory usage, and network usage.
29. Checking Node Resources
To check the resources of your node, use the
This will display resource metrics for your node, including disk usage, network bandwidth, and memory usage.
30. Checking Node Health
To check the health of your node, use the
This will display health metrics for your node, including block synchronization status, network connectivity, and resource usage.
31. Checking Node Statistics
To check the statistics of your node, use the
This will display statistical data for your node, including the number of transactions processed, the number of blocks produced, and the number of network connections.
32. Checking Node Debug Information
To check the debug information of your node, use the
This will display debug information for your node, which can be useful for troubleshooting issues or optimizing performance.
33. Checking Node Blockchain Information
To check the blockchain information of your node, use the
This will display blockchain information for your node, including the current block height, the total number of transactions, and the total supply of tokens.
34. Checking Node Network Information
To check the network information of your node, use the
This will display network information for your node, including the number of connected peers, the total bandwidth usage, and the current network protocol version.
35. Checking Node Wallet Information
To check the wallet information of your node, use the
This will display wallet information for your node, including the current balance, the total number of transactions, and the current wallet address.
36. Checking Node Contract Information
To check the contract information of your node, use the
This will display contract information for your node, including the total number of contracts, the total number of contract calls, and the current contract gas limit.
37. Checking Node Transaction Information
To check the transaction information of your node, use the
This will display transaction information for your node, including the total number of transactions, the total transaction fees, and the current transaction gas limit.
38. Checking Node Mining Information
To check the mining information of your node, use the
This will display mining information for your node, including the total number of blocks mined, the total mining rewards, and the current mining difficulty.
39. Checking Node Syncing Information
To check the syncing information of your node, use the
This will display syncing information for your node, including the current block height, the highest known block, and the syncing status.
40. Checking Node Peer Information
To check the peer information of your node, use the
This will display peer information for your node, including the total number of peers, the number of inbound and outbound connections, and the peer discovery status.
41. Checking Node Consensus Information
To check the consensus information of your node, use the
This will display consensus information for your node, including the current consensus algorithm, the total number of validators, and the consensus status.
42. Checking Node Governance Information
To check the governance information of your node, use the
This will display governance information for your node, including the current governance model, the total number of proposals, and the governance status.
43. Checking Node Staking Information
To check the staking information of your node, use the
This will display staking information for your node, including the total amount of staked tokens, the number of stakers, and the staking rewards.
44. Checking Node Delegation Information
To check the delegation information of your node, use the
This will display delegation information for your node, including the total amount of delegated tokens, the number of delegators, and the delegation rewards.
45. Checking Node Voting Information
To check the voting information of your node, use the
This will display voting information for your node, including the total number of votes, the number of voters, and the voting results.
46. Checking Node Proposal Information
To check the proposal information of your node, use the
This will display proposal information for your node, including the total number of proposals, the number of proposal creators, and the proposal results.