aitbc/cli/CLI_USAGE_GUIDE.md

AITBC CLI - Complete Usage Guide

Overview

The AITBC CLI provides comprehensive blockchain and wallet management capabilities with professional-grade features and user-friendly interfaces.

Installation

The CLI tool is located at /opt/aitbc/aitbc-cli and is deployed on both aitbc and aitbc1 nodes. The tool is accessible via the aitbc alias after sourcing your shell configuration.

Commands

The AITBC CLI provides 27 commands for comprehensive blockchain management:

Available Commands

• create - Create a new wallet
• send - Send AIT
• list - List wallets
• balance - Get wallet balance
• transactions - Get wallet transactions
• chain - Get blockchain information
• network - Get network status
• analytics - Blockchain analytics and statistics
• marketplace - Marketplace operations
• ai-ops - AI compute operations
• mining - Mining operations and status
• agent - AI agent workflow and execution management
• openclaw - OpenClaw agent ecosystem operations
• workflow - Workflow automation and management
• resource - Resource management and optimization
• system - System status and information
• blockchain - Blockchain operations
• wallet - Wallet operations
• all-balances - Show all wallet balances
• import - Import wallet from private key
• export - Export private key from wallet
• delete - Delete wallet
• rename - Rename wallet
• batch - Send multiple transactions
• market-list - List marketplace items
• market-create - Create marketplace listing
• ai-submit - Submit AI compute job
• simulate - Simulate blockchain scenarios and test environments

1. List Wallets

Display all available wallets with their addresses.

aitbc list

Output:

Wallets:
  openclaw-backup: ait1cebd266469be5f85b5f0052f1556b5d708b42de9
  openclaw-trainee: ait10a252a31c79939c689bf392e960afc7861df5ee9

2. Get Balance

Retrieve wallet balance, nonce, and address information.

aitbc balance --name <wallet-name>

Examples:

# Get balance for specific wallet
aitbc balance --name openclaw-backup

Output:

Wallet: openclaw-backup
Address: ait1cebd266469be5f85b5f0052f1556b5d708b42de9
Balance: 0 AIT
Nonce: 0

3. Get Chain Information

Display blockchain network information and configuration.

aitbc chain

Output:

Blockchain Information:
  Chain ID: ait-mainnet
  Supported Chains: ait-mainnet
  Height: 22502
  Latest Block: 0x4d6cfbf2c3e758...
  Proposer: none

4. Get Network Status

Display current network status and health information.

aitbc network

Output:

Network Status:
  Height: 22502
  Latest Block: 0x4d6cfbf2c3e758...
  Chain ID: ait-mainnet
  Tx Count: 0
  Timestamp: 2026-03-31T13:24:55.238626

5. System Status

Get comprehensive system status and information.

aitbc system

Output:

System operation completed

6. Analytics

Get blockchain analytics and statistics.

aitbc analytics

Output:

Blockchain Analytics (blocks):
  Current Height: 22502
  Latest Block: 0x4d6cfbf2c3e75831e93a6f400ac3c8ccef86c17b5b3a1e0cf88013e6173f9cf2
  Timestamp: 2026-03-31T13:24:55.238626
  Tx Count: 0
  Status: Active

7. Marketplace Operations

List marketplace items and create listings.

# List marketplace items
aitbc marketplace --action list

# Create marketplace listing
aitbc marketplace --action create --name <name> --price <price> --description <description>

Output:

Marketplace list:
  Items: [{'name': 'AI Compute Hour', 'price': 100, 'provider': 'GPU-Miner-1'}, ...]
  Total Items: 3

8. Wallet Operations

Comprehensive wallet management.

# Wallet operations
aitbc wallet

# All balances
aitbc all-balances

Advanced Features

Output Formats

Most commands support both table and JSON output formats:

# Table format (human-readable)
/opt/aitbc/aitbc-cli wallet list --format table

# JSON format (machine-readable)
/opt/aitbc/aitbc-cli wallet list --format json

Remote Node Operations

Connect to different RPC endpoints:

# Local node
/opt/aitbc/aitbc-cli wallet balance my-wallet --rpc-url http://localhost:8006

# Remote node
/opt/aitbc/aitbc-cli wallet balance my-wallet --rpc-url http://10.1.223.40:8006

Password Management

Multiple password input methods:

# Password file
/opt/aitbc/aitbc-cli wallet send wallet --to address --amount 100 --password-file /path/to/password

# Interactive password
/opt/aitbc/aitbc-cli wallet send wallet --to address --amount 100

# Direct password (not recommended for production)
/opt/aitbc/aitbc-cli wallet send wallet --to address --amount 100 --password mypassword

Common Workflows

1. Complete Wallet Setup

# Create wallet
/opt/aitbc/aitbc-cli wallet create my-wallet --password-file /var/lib/aitbc/keystore/.password

# Get wallet address
WALLET_ADDR=$(/opt/aitbc/aitbc-cli wallet balance my-wallet --format json | jq -r '.address')

# Check balance
/opt/aitbc/aitbc-cli wallet balance my-wallet

2. Transaction Workflow

# Check sender balance
/opt/aitbc/aitbc-cli wallet balance sender-wallet

# Send transaction
/opt/aitbc/aitbc-cli wallet send sender-wallet --to $WALLET_ADDR --amount 1000 --password-file /var/lib/aitbc/keystore/.password

# Monitor transaction
/opt/aitbc/aitbc-cli wallet transactions sender-wallet --limit 3

# Check recipient balance
/opt/aitbc/aitbc-cli wallet balance recipient-wallet

3. Network Monitoring

# Check network status
/opt/aitbc/aitbc-cli network status

# Check chain information
/opt/aitbc/aitbc-cli blockchain info

# List all wallets
/opt/aitbc/aitbc-cli wallet list

# Check all wallet balances
for wallet in $(/opt/aitbc/aitbc-cli wallet list --format json | jq -r '.[].name'); do
  echo "Wallet: $wallet"
  /opt/aitbc/aitbc-cli wallet balance $wallet
  echo "---"
done

Cross-Node Operations

aitbc1 to aitbc Operations

# On aitbc1 - check network status
/opt/aitbc/aitbc-cli network status

# On aitbc - check network status
ssh aitbc '/opt/aitbc/aitbc-cli network status'

# Send from aitbc1 to aitbc wallet
/opt/aitbc/aitbc-cli wallet send genesis --to $AITBC_WALLET_ADDR --amount 1000 --password-file /var/lib/aitbc/keystore/.password

# Check balance on aitbc
ssh aitbc "/opt/aitbc/aitbc-cli wallet balance aitbc-user"

Error Handling

The CLI provides comprehensive error handling with specific exception types:

Improved Error Handling (April 2026)

Recent improvements to error handling across all services:

• Specific Exception Types: Replaced generic except Exception with specific exception types
• Network Errors: ConnectionError, Timeout, HTTPError for network operations
• File Operations: FileNotFoundError, PermissionError, IOError for file access
• Data Processing: JSONDecodeError, KeyError, StopIteration for data operations
• System Errors: OSError, psutil.Error for system operations

Service Error Handling

All services now have improved error handling:

• monitor.py: Handles JSON decode errors, file not found, permission errors
• real_marketplace_launcher.py: Handles subprocess errors, file access errors
• blockchain_http_launcher.py: Handles subprocess errors, connection issues
• gpu_marketplace_launcher.py: Handles subprocess errors, system errors
• miner_management.py: Handles network errors, JSON decode errors, data processing errors

CLI Error Messages

The CLI provides clear, actionable error messages:

• Wallet Not Found: Clear error message when wallet doesn't exist
• Invalid Parameters: Detailed parameter validation errors
• Network Errors: RPC connectivity issues with helpful messages
• Transaction Errors: Detailed transaction failure information
• System Errors: System-level error information with context

Security Best Practices

1. Password Management: Use password files instead of command-line passwords
2. File Permissions: Ensure keystore files have proper permissions (600)
3. Network Security: Use HTTPS for RPC endpoints in production
4. Backup: Regularly backup keystore files
5. Validation: Always verify transaction details before sending

Performance Optimizations

Database Connection Pooling (April 2026)

Recent performance improvements to database operations:

• Connection Pooling: Configured for PostgreSQL/MySQL (pool_size=10, max_overflow=20)
• Connection Validation: pool_pre_ping=True to verify connections before use
• Connection Recycling: pool_recycle=3600 to recycle connections after 1 hour
• SQLite Optimization: StaticPool for SQLite with timeout configuration

Cache Management (April 2026)

Enhanced cache system with memory management:

• Memory Limits: Configured max_size=1000, max_memory_mb=100
• Automatic Eviction: Oldest entries evicted when size limit reached
• Memory Monitoring: Periodic memory limit checking and garbage collection
• Performance Tracking: Cache hit rate and statistics monitoring

Performance Metrics

The system now tracks comprehensive performance metrics:

• Cache Hit Rate: Monitors cache effectiveness
• Operation Timing: Tracks execution time for all operations
• Error Rates: Monitors error frequency and types
• Resource Usage: Tracks memory and CPU usage patterns

Optimization Recommendations

1. Use Cache: Leverage caching for frequently accessed data
2. Connection Pooling: Database connections are pooled for efficiency
3. Batch Operations: Use batch commands when possible
4. Monitor Performance: Use analytics command to check system performance

Integration with Scripts

The CLI is designed for easy integration with shell scripts:

#!/bin/bash
# Get wallet balance in script
BALANCE=$(/opt/aitbc/aitbc-cli wallet balance my-wallet --format json | jq -r '.balance')

if [ "$BALANCE" -gt "1000" ]; then
  echo "Sufficient balance for transaction"
  /opt/aitbc/aitbc-cli wallet send my-wallet --to $RECIPIENT --amount 1000 --password-file /var/lib/aitbc/keystore/.password
else
  echo "Insufficient balance: $BALANCE AIT"
fi

Troubleshooting

Common Issues

1. Permission Denied: Check file permissions on keystore directory
2. Connection Refused: Verify RPC service is running
3. Invalid Password: Ensure password file contains correct password
4. Wallet Not Found: Verify wallet name is correct

Debug Mode

Add verbose output for debugging:

# Enable debug output (if implemented)
/opt/aitbc/aitbc-cli --debug balance --name my-wallet

Future Enhancements

Planned features for future releases:

• Batch Operations: Send multiple transactions in one command
• Smart Contracts: Deploy and interact with smart contracts
• Staking: Delegate and undelegate tokens
• Governance: Participate in governance proposals
• NFT Support: Create and manage NFTs
• Multi-signature: Create and manage multi-sig wallets

Support

For support and issues:

1. Check the error messages for specific guidance
2. Verify network connectivity and service status
3. Review this documentation for proper usage
4. Check system logs for additional error details