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-cli2. 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:
help transferSome 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 connect command:
connect https://api.koinos.io/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.
Example:
create my.wallet password1234This will create a new wallet file named my.wallet with the password password1234.
To open a previously created wallet, use the command open <filename> <password>.
Example:
open my.wallet password1234This will open the wallet file named my.wallet using the password password1234.
To import an existing Wallet Import Format (WIF) private key, use the commands import <wif> <filename> <password>.
Example:
import 5KPJcpkw7GBtxjNrzroYgVwjR8CnTwbPrybuwfb8ff1Hw4GcqB5 imported.wallet password1234This will import the private key into a new wallet file named imported.wallet with the password password1234.
To close the open wallet, simply use the close command:
close4. Other Useful Commands
To check the balance of a given public address, use the command balance <address>.
For example, to check the balance of the address 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM, you would type:
balance 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyMTo 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 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM5. 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.
Example:
upload token.wasmThis will upload the smart contract contained in the file token.wasm.
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.
Example:
register koin 15im92XgZiV39tcKMhMGtDYhJjXPMjUu8r abi/koin.abiThis will register the ABI file koin.abi for the smart contract at address 15im92XgZiV39tcKMhMGtDYhJjXPMjUu8r under the name koin.
Its methods will then be added to the list of available commands in the CLI.
Example:
koin.balance_of 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyMThis 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 session view.
To cancel the current session, use session cancel.
When you are done adding commands to the session, session submit will send the attached commands as a single transaction to the blockchain.
Example:
session begin
transfer 1.0 1BLUi4ogqptnyBnSuKFyWMxEyVJzxiZWhM
upload token.wasm
transfer 25.0 15Pb7o5GFBB56njFNvU2fAfa9Mm7rmsJH1
session view
session submitThis 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 exit or quit command:
exitor
quit9. 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
the connect command:
connect https://api.koinos.io/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:
create my.wallet11. 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:
koin.balance_of 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyMTo transfer tokens from a registered smart contract, you could use:
koin.transfer 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyM 13daTg586CnrVjKRjGwBtBWH6eda99A7bw 100000000And to check the balance of the receiving address after the transfer, you could use:
koin.balance_of 13daTg586CnrVjKRjGwBtBWH6eda99A7bw12. Checking Node Status
To check the status of your node, use the status command:
statusThis 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:
transaction_status 1234567890abcdefReplace 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:
block_info 12345Replace 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:
account_info 1H7NoCkYiVciGLGA92LyAR2VvFLNN38qyMReplace 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:
contract_info 15im92XgZiV39tcKMhMGtDYhJjXPMjUu8rReplace 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:
send_raw_transaction 0102030405060708090a0b0c0d0e0fReplace 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:
broadcast_transaction 0102030405060708090a0b0c0d0e0fReplace 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 network_connections command:
network_connectionsThis 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:
disconnect 192.168.1.1Replace 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:
connect 192.168.1.1Replace 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 config command:
configThis 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 50Replace 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 logs command:
logsThis 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 version command:
versionThis 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 uptime command:
uptimeThis 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 peers command:
peersThis 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 performance command:
performanceThis 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 resources command:
resourcesThis 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 health command:
healthThis 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 stats command:
statsThis 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 debug command:
debugThis 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 blockchain command:
blockchainThis 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 network command:
networkThis 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 wallet command:
walletThis 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 contract command:
contractThis 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 transaction command:
transactionThis 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 mining command:
miningThis 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 syncing command:
syncingThis 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 peer command:
peerThis 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 consensus command:
consensusThis 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 governance command:
governanceThis 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 staking command:
stakingThis 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 delegation command:
delegationThis 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 voting command:
votingThis 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 proposal command:
proposalThis will display proposal information for your node, including the total number of proposals, the number of proposal creators, and the proposal results.