ChainOS CLI Guide

Command Line Interface

The ChainOS CLI provides a powerful interface for interacting with the blockchain, managing wallets, sending transactions, and querying network information.

Installation & Setup

The ChainOS CLI is included in the main ChainOS repository. To get started:

# Clone the repository
git clone https://github.com/o-c-foundation/ChainOS--Mainnet.git
cd ChainOS--Mainnet

# Make the CLI script executable
chmod +x chainos-cli.sh

Configuration

The CLI uses the following environment variables which can be configured in your shell or directly in the script:

# Default configuration
NODE="tcp://chainos.network:26657"  # RPC endpoint
CHAIN_ID="chainos-1"                # Chain ID
HOME_DIR="$HOME/.chainosd"          # Configuration directory

You can customize these variables by editing the script or setting them in your environment:

# Example: Connect to a local node
export NODE="tcp://localhost:26657"
export CHAIN_ID="chainos-testnet-1"
export HOME_DIR="$HOME/.chainosd-testnet"

Basic Usage

The ChainOS CLI can be used in two modes:

Interactive Mode

Launch the CLI in interactive mode to access a menu-driven interface:

./chainos-cli.sh

This will display the main menu with various options:

===== ChainOS CLI =====
1) Wallet Management
2) Transaction Operations
3) Query Information
4) Validator Operations
5) Governance
6) Advanced Options
7) Exit
Enter your choice [1-7]:

Command Mode

Execute specific commands directly from your shell:

./chainos-cli.sh [command] [subcommand] [arguments]

For example:

# Query account balance
./chainos-cli.sh query balance mywalletname

# Send tokens
./chainos-cli.sh tx send mywalletname recipient_address 100uos

Wallet Management

The CLI provides comprehensive wallet management features:

Create a New Wallet

# Interactive mode
./chainos-cli.sh
# Select: 1) Wallet Management > 1) Create New Wallet

# Command mode
./chainos-cli.sh wallet create mywallet

When creating a wallet, you'll receive a 24-word mnemonic phrase. Important: Store this phrase securely as it's the only way to recover your wallet!

Recover a Wallet

# Interactive mode
./chainos-cli.sh
# Select: 1) Wallet Management > 2) Recover Wallet

# Command mode
./chainos-cli.sh wallet recover mywallet

You'll be prompted to enter your 24-word mnemonic phrase.

List Wallets

# Interactive mode
./chainos-cli.sh
# Select: 1) Wallet Management > 3) List Wallets

# Command mode
./chainos-cli.sh wallet list

Show Wallet Address

# Interactive mode
./chainos-cli.sh
# Select: 1) Wallet Management > 4) Show Wallet Address

# Command mode
./chainos-cli.sh wallet show mywallet

Delete a Wallet

# Interactive mode
./chainos-cli.sh
# Select: 1) Wallet Management > 5) Delete Wallet

# Command mode
./chainos-cli.sh wallet delete mywallet

Warning: Make sure you have backed up your mnemonic phrase before deleting a wallet!

Transaction Operations

The CLI allows you to perform various transaction operations:

Send Tokens

# Interactive mode
./chainos-cli.sh
# Select: 2) Transaction Operations > 1) Send Tokens

# Command mode
./chainos-cli.sh tx send mywallet chainos1recipient... 100uos --memo "Payment for services"

The amount should be specified in uos (microUOS), where 1 UOS = 1,000,000 uos.

Delegate Tokens

# Interactive mode
./chainos-cli.sh
# Select: 2) Transaction Operations > 2) Delegate Tokens

# Command mode
./chainos-cli.sh tx delegate mywallet chainosvaloper1... 1000000uos

Redelegate Tokens

# Interactive mode
./chainos-cli.sh
# Select: 2) Transaction Operations > 3) Redelegate Tokens

# Command mode
./chainos-cli.sh tx redelegate mywallet src_validator_addr dst_validator_addr 1000000uos

Undelegate Tokens

# Interactive mode
./chainos-cli.sh
# Select: 2) Transaction Operations > 4) Undelegate Tokens

# Command mode
./chainos-cli.sh tx undelegate mywallet validator_addr 1000000uos

Note: Undelegated tokens are subject to a 21-day unbonding period before they become available.

Withdraw Rewards

# Interactive mode
./chainos-cli.sh
# Select: 2) Transaction Operations > 5) Withdraw Rewards

# Command mode
# Withdraw from a specific validator
./chainos-cli.sh tx withdraw-rewards mywallet validator_addr

# Withdraw from all validators
./chainos-cli.sh tx withdraw-all-rewards mywallet

Query Information

The CLI provides various query commands to retrieve information from the blockchain:

Query Account Balance

# Interactive mode
./chainos-cli.sh
# Select: 3) Query Information > 1) Query Balance

# Command mode
./chainos-cli.sh query balance mywallet

Query Transaction

# Interactive mode
./chainos-cli.sh
# Select: 3) Query Information > 2) Query Transaction

# Command mode
./chainos-cli.sh query tx HASH

Replace HASH with the transaction hash you want to query.

Query Validator

# Interactive mode
./chainos-cli.sh
# Select: 3) Query Information > 3) Query Validator

# Command mode
./chainos-cli.sh query validator chainosvaloper1...

Query All Validators

# Interactive mode
./chainos-cli.sh
# Select: 3) Query Information > 4) Query All Validators

# Command mode
./chainos-cli.sh query validators

Query Delegations

# Interactive mode
./chainos-cli.sh
# Select: 3) Query Information > 5) Query Delegations

# Command mode
./chainos-cli.sh query delegations mywallet

Query Network Parameters

# Interactive mode
./chainos-cli.sh
# Select: 3) Query Information > 6) Query Network Parameters

# Command mode
./chainos-cli.sh query params

Validator Operations

If you're running a validator node, the CLI provides commands for validator operations:

Create Validator

# Interactive mode
./chainos-cli.sh
# Select: 4) Validator Operations > 1) Create Validator

# Command mode
./chainos-cli.sh tx create-validator \
  --from mywallet \
  --amount 1000000uos \
  --pubkey $(chainosd tendermint show-validator) \
  --moniker "my-validator-name" \
  --website "https://myvalidator.com" \
  --details "My validator description" \
  --commission-rate 0.10 \
  --commission-max-rate 0.20 \
  --commission-max-change-rate 0.01 \
  --min-self-delegation 1

Edit Validator

# Interactive mode
./chainos-cli.sh
# Select: 4) Validator Operations > 2) Edit Validator

# Command mode
./chainos-cli.sh tx edit-validator \
  --from mywallet \
  --moniker "new-name" \
  --website "https://newwebsite.com" \
  --details "New description" \
  --commission-rate 0.12

Unjail Validator

# Interactive mode
./chainos-cli.sh
# Select: 4) Validator Operations > 3) Unjail Validator

# Command mode
./chainos-cli.sh tx unjail --from mywallet

Governance

Participate in on-chain governance using these commands:

Submit Proposal

# Interactive mode
./chainos-cli.sh
# Select: 5) Governance > 1) Submit Proposal

# Command mode
# Text proposal
./chainos-cli.sh tx submit-proposal \
  --title "My Proposal" \
  --description "This is a proposal to..." \
  --type text \
  --deposit 10000000uos \
  --from mywallet

# Parameter change proposal
./chainos-cli.sh tx submit-proposal param-change proposal.json --from mywallet

Deposit to Proposal

# Interactive mode
./chainos-cli.sh
# Select: 5) Governance > 2) Deposit to Proposal

# Command mode
./chainos-cli.sh tx deposit 1 10000000uos --from mywallet

Vote on Proposal

# Interactive mode
./chainos-cli.sh
# Select: 5) Governance > 3) Vote on Proposal

# Command mode
./chainos-cli.sh tx vote 1 yes --from mywallet

Vote options: yes, no, no_with_veto, abstain

Query Proposals

# Interactive mode
./chainos-cli.sh
# Select: 5) Governance > 4) Query Proposals

# Command mode
# Query all proposals
./chainos-cli.sh query proposals

# Query specific proposal
./chainos-cli.sh query proposal 1

Advanced Options

The CLI also provides advanced functionality for power users:

Multisig Transactions

Create and manage multisignature wallets:

# Create a multisig key
./chainos-cli.sh keys add multisig-wallet --multisig wallet1,wallet2,wallet3 --multisig-threshold 2

# Generate a transaction for signing
./chainos-cli.sh tx send multisig-wallet recipient 1000000uos --generate-only > unsigned.json

# Sign with first key
./chainos-cli.sh tx sign unsigned.json --from wallet1 > signed1.json

# Sign with second key
./chainos-cli.sh tx sign unsigned.json --from wallet2 > signed2.json

# Combine signatures
./chainos-cli.sh tx multisign unsigned.json multisig-wallet signed1.json signed2.json > signed.json

# Broadcast transaction
./chainos-cli.sh tx broadcast signed.json

Offline Signing

Sign transactions offline for enhanced security:

# Generate unsigned transaction
./chainos-cli.sh tx send mywallet recipient 1000000uos --generate-only > unsigned.json

# Sign transaction offline
./chainos-cli.sh tx sign unsigned.json --from mywallet --offline > signed.json

# Broadcast signed transaction
./chainos-cli.sh tx broadcast signed.json

Connect to Custom Node

Specify a custom node for a single command:

./chainos-cli.sh query balance mywallet --node tcp://custom-node:26657

Troubleshooting

Here are solutions to common issues you might encounter:

Connection Issues

Symptoms: "Error: connection refused" or timeout errors

Solutions:

Verify the node URL is correct
Check if the node is running and accessible
Try connecting to a different node: --node tcp://alternate-node:26657

Insufficient Funds

Symptoms: "insufficient funds" error when sending transactions

Solutions:

Check your balance: ./chainos-cli.sh query balance mywallet
Remember to account for transaction fees
Ensure you're not trying to send your entire balance without leaving funds for fees

Out of Gas

Symptoms: "out of gas" errors

Solutions:

Increase the gas limit: --gas 200000
Use auto gas estimation: --gas auto
Adjust the gas prices: --gas-prices 0.025uos

Account Sequence Mismatch

Symptoms: "account sequence mismatch" errors

Solutions:

Wait for previous transaction to be processed
Reset your account sequence: --sequence [number]
Query your account to get the correct sequence: ./chainos-cli.sh query account mywallet

CLI Reference

Here's a quick reference of commonly used commands:

# Wallet Management
./chainos-cli.sh wallet create WALLET_NAME
./chainos-cli.sh wallet recover WALLET_NAME
./chainos-cli.sh wallet list
./chainos-cli.sh wallet show WALLET_NAME
./chainos-cli.sh wallet delete WALLET_NAME

# Transactions
./chainos-cli.sh tx send WALLET_NAME TO_ADDRESS AMOUNT
./chainos-cli.sh tx delegate WALLET_NAME VALIDATOR_ADDRESS AMOUNT
./chainos-cli.sh tx redelegate WALLET_NAME SRC_VAL DST_VAL AMOUNT
./chainos-cli.sh tx undelegate WALLET_NAME VALIDATOR_ADDRESS AMOUNT
./chainos-cli.sh tx withdraw-rewards WALLET_NAME VALIDATOR_ADDRESS
./chainos-cli.sh tx withdraw-all-rewards WALLET_NAME

# Queries
./chainos-cli.sh query balance WALLET_NAME
./chainos-cli.sh query tx TX_HASH
./chainos-cli.sh query validator VALIDATOR_ADDRESS
./chainos-cli.sh query validators
./chainos-cli.sh query delegations WALLET_NAME
./chainos-cli.sh query params

# Validator Operations
./chainos-cli.sh tx create-validator [OPTIONS]
./chainos-cli.sh tx edit-validator [OPTIONS]
./chainos-cli.sh tx unjail --from WALLET_NAME

# Governance
./chainos-cli.sh tx submit-proposal [OPTIONS]
./chainos-cli.sh tx deposit PROPOSAL_ID AMOUNT --from WALLET_NAME
./chainos-cli.sh tx vote PROPOSAL_ID VOTE_OPTION --from WALLET_NAME
./chainos-cli.sh query proposals
./chainos-cli.sh query proposal PROPOSAL_ID

Need Help?

If you encounter any issues not covered in this guide, join our Discord community for support from the team and other users.