Node CLI Usage Guide

This reference manual covers the xosd command-line interface (CLI) for the XOS Testnet. Designed for operators who wish to gain deeper control over their node operations, this guide documents available commands, their functions, and practical usage examples.

Command Structure

The xosd CLI follows a hierarchical organization with primary commands that branch into more specific subcommands. To explore available subcommands, use:

xosd <command> --help

For comprehensive command documentation, execute:

xosd --help

This displays all available commands with their descriptions. The following sections examine each major command category in detail.

Node Configuration Management

xosd config

This command group facilitates node configuration management, allowing you to inspect and modify configuration parameters.

Subcommand	Function
diff	Lists all configuration values that deviate from the default app.toml settings.
get	Retrieves the current setting for a specific configuration parameter.
home	Shows the directory path used as the binary's home location. (Not applicable when using confix independently.)
migrate	Converts a Cosmos SDK configuration file to another version format.
set	Updates a configuration parameter with a new value.
view	Displays the complete contents of the configuration file.

Usage Examples

• Identify non-default configuration:

  xosd config diff

• Retrieve a parameter value:

  xosd config get <parameter_name>

• Modify a parameter:

  xosd config set <parameter_name> <parameter_value>

• View entire configuration:

  xosd config view

Cryptographic Key Operations

xosd keys

This command suite handles all operations related to cryptographic key management, including creation, import, export, and other key-related functions.

Advanced security considerations

Proper key management is crucial for secure node operation. For production validators, review the detailed security practices outlined in the Key Management Guide.

Subcommand	Function
add	Creates a new key or recovers an existing one, encrypts it, and saves it with a specified name.
delete	Removes a key from local storage.
export	Exports a key in encrypted or unencrypted format depending on specified options.
import	Adds a previously exported key to the local keystore.
list	Displays all keys currently stored in the local keystore.
migrate	Converts keys from Amino encoding to Proto serialization format.
mnemonic	Generates or derives BIP39 mnemonic phrases from provided entropy.
parse	Converts addresses between hexadecimal and Bech32 encoding formats.
rename	Changes the name identifier for a stored key.
show	Displays detailed information about a specific key, including its public address.
unsafe-export-eth-key	UNSAFE: Extracts an Ethereum private key. Exercise extreme caution.
unsafe-import-eth-key	UNSAFE: Incorporates an Ethereum private key into the local keystore. Exercise extreme caution.

Usage Examples

• Generate a new key:

  xosd keys add myOperationalKey

• View all available keys:

  xosd keys list

• Extract a key:

  xosd keys export myOperationalKey

• Remove a key:

  xosd keys delete myOperationalKey

Blockchain Data Retrieval

xosd query

The query command suite enables retrieval of blockchain data across various modules, transactions, blocks, and state information. For command-specific help, use xosd query <subcommand> --help.

The following subcommands are available:

Subcommand	Function
auth	Retrieves data from the authentication module.
authz	Accesses authorization module information.
bank	Fetches account balances and related bank module data.
block	Retrieves block information by height, hash, or event criteria.
block-results	Obtains execution results for a specified block height.
blocks	Returns multiple blocks matching specified event criteria with pagination.
comet-validator-set	Displays the complete CometBFT validator set at a designated block height.
consensus	Retrieves current consensus parameter values.
distribution	Accesses reward distribution data (commissions, rewards, etc.).
erc20	Retrieves information related to ERC-20 contracts.
evidence	Searches for evidence of validator misbehavior.
evm	Accesses Ethereum Virtual Machine module data.
feegrant	Retrieves information about fee allowances.
feemarket	Obtains fee market module data and parameters.
gov	Accesses governance information including proposals, votes, and deposits.
ibc	Retrieves Inter-Blockchain Communication protocol data.
ibc-transfer	Fetches IBC token transfer details.
interchain-accounts	Accesses IBC interchain account information.
params	Retrieves blockchain parameters.
poa	Fetches Proof-of-Authority module data.
ratelimit	Retrieves rate-limit module configuration and status.
slashing	Accesses validator slashing information, signing records, and parameters.
staking	Retrieves validator and delegation data including staking positions and unbonding records.
tx	Locates a specific transaction using its hash, address/sequence, or signature.
txs	Searches for multiple transactions using event criteria.
upgrade	Retrieves information about pending and completed network upgrades.
wait-tx	Monitors and waits for a transaction to be confirmed in a block.

Usage Examples

• Check address balance:

  xosd query bank balances <account_address>

• Retrieve latest block data:

  xosd query block

• Examine transaction details:

  xosd query tx <transaction_hash>

Blockchain State Modification

xosd tx

The transaction command suite facilitates operations that modify blockchain state. These commands allow you to create, sign, validate, and broadcast various types of transactions.

Available transaction subcommands:

Subcommand	Function
auth	Executes authentication module transactions.
authz	Manages authorization operations (granting, revoking, etc.).
bank	Facilitates token transfers and other banking operations.
broadcast	Transmits prepared transaction data to the network.
consensus	Handles consensus parameter modification transactions.
crisis	Provides emergency chain management functionality.
decode	Converts binary transaction data to human-readable format.
distribution	Manages reward distribution operations.
encode	Converts transactions to binary format for transmission.
erc20	Facilitates ERC-20 token-related operations.
evidence	Submits evidence of validator protocol violations.
evm	Manages Ethereum Virtual Machine operations.
feegrant	Executes fee allowance management operations.
feemarket	Handles fee market parameter modifications.
gov	Facilitates governance operations (proposal submission, voting, etc.).
ibc	Executes Inter-Blockchain Communication operations.
ibc-transfer	Performs cross-chain token transfers.
interchain-accounts	Manages IBC interchain account operations.
multi-sign	Creates signatures for multi-signature transactions.
multisign-batch	Processes batch transactions with multiple signatures.
poa	Executes Proof-of-Authority module transactions.
ratelimit	Manages rate-limit module parameters.
sign	Adds a cryptographic signature to a transaction.
sign-batch	Signs multiple transactions simultaneously.
simulate	Performs transaction simulation to estimate execution costs.
slashing	Submits validator slashing-related transactions.
staking	Manages validator staking operations (delegation, unbonding, etc.).
upgrade	Submits network upgrade proposals.
validate-signatures	Verifies transaction signature validity.

Usage Examples

• Transfer tokens between accounts:

  xosd tx bank send <sender_address> <recipient_address> <token_amount> --gas auto --gas-adjustment 1.2

• Submit governance proposal:

  xosd tx gov submit-proposal <proposal_type> --title "<Proposal Title>" --description "<Proposal Description>" ...

• Estimate transaction execution cost:

  xosd tx simulate --file <transaction_file>

Software Version Information

xosd version

Displays the installed xosd binary version details. This information is essential for verifying compatibility with the XOS Testnet network.

Usage Example

xosd version