aitbc/docs/CLI_DOCUMENTATION.md

AITBC CLI Documentation

Overview

The AITBC CLI (Command Line Interface) is a comprehensive tool for managing the AITBC blockchain network, AI operations, marketplace interactions, agent workflows, and advanced economic intelligence operations. With the AI Economics Masters transformation, the CLI now provides sophisticated economic modeling and marketplace strategy capabilities.

🚀 New in v0.2.3: AI Economics Masters Integration

Economic Intelligence Commands

• Distributed AI Job Economics: Cross-node cost optimization and revenue sharing
• Marketplace Strategy: Dynamic pricing and competitive positioning
• Investment Management: Portfolio optimization and ROI tracking
• Economic Modeling: Predictive economics and market forecasting

Installation

Prerequisites

• Python 3.13+
• Virtual environment at /opt/aitbc/venv
• AITBC services running on ports 8000, 8001, 8006

Setup

cd /opt/aitbc
source venv/bin/activate
./aitbc-cli --version

Command Structure

Core Commands

Wallet Management

# Create new wallet
./aitbc-cli create --name wallet-name --password your-password

# List all wallets
./aitbc-cli list

# Get wallet balance
./aitbc-cli balance --name wallet-name

# Send AIT
./aitbc-cli send --from from-wallet --to to-wallet --amount 100 --password your-password

# Get wallet transactions
./aitbc-cli transactions --name wallet-name --limit 10

Blockchain Operations

# Get blockchain information
./aitbc-cli chain [--rpc-url http://localhost:8006]

# Get network status
./aitbc-cli network

# Get blockchain analytics
./aitbc-cli analytics

AI Operations

# Submit AI job
./aitbc-cli ai-submit --wallet wallet-name --type inference --prompt "Generate image" --payment 100

# Check AI job status
./aitbc-cli ai-ops --action status --job-id job-id

# Get AI job results
./aitbc-cli ai-ops --action results --job-id job-id

# Advanced AI Operations - Phase 1 Completed
./aitbc-cli ai-submit --wallet genesis-ops --type parallel --prompt "Complex AI pipeline for medical diagnosis" --payment 500
./aitbc-cli ai-submit --wallet genesis-ops --type ensemble --prompt "Parallel AI processing with ensemble validation" --payment 600

# Advanced AI Operations - Phase 2 Completed
./aitbc-cli ai-submit --wallet genesis-ops --type multimodal --prompt "Multi-modal customer feedback analysis with cross-modal attention" --payment 1000
./aitbc-cli ai-submit --wallet genesis-ops --type fusion --prompt "Cross-modal fusion with joint reasoning and consensus validation" --payment 1200

# Advanced AI Operations - Phase 3 Completed
./aitbc-cli ai-submit --wallet genesis-ops --type resource-allocation --prompt "Dynamic resource allocation system with GPU pools and demand forecasting" --payment 800
./aitbc-cli ai-submit --wallet genesis-ops --type performance-tuning --prompt "AI performance optimization for sub-100ms inference latency" --payment 1000

Marketplace Operations

# List marketplace items
./aitbc-cli marketplace --action list

# Create marketplace listing
./aitbc-cli marketplace --action create --name "Service Name" --price 100 --description "Description" --wallet wallet-name

# Search marketplace
./aitbc-cli marketplace --action search --query "search term"

# View my listings
./aitbc-cli marketplace --action my-listings --wallet wallet-name

Resource Management

# Get resource status
./aitbc-cli resource --action status

# Allocate resources
./aitbc-cli resource --action allocate --agent-id agent-name --cpu 4 --memory 8192 --duration 3600

Mining Operations

# Start mining
./aitbc-cli mine-start

# Stop mining
./aitbc-cli mine-stop

# Check mining status
./aitbc-cli mine-status

Advanced Commands

Agent Operations

# Run agent workflow
./aitbc-cli agent --agent agent-name --message "Task description" --thinking high

# OpenClaw operations
./aitbc-cli openclaw --action status

Workflow Operations

# Run workflow
./aitbc-cli workflow --name workflow-name --parameters "param1=value1,param2=value2"

Simulation Commands

# Simulate blockchain
./aitbc-cli simulate blockchain --blocks 10 --transactions 50 --delay 1.0

# Simulate wallets
./aitbc-cli simulate wallets --wallets 5 --balance 1000 --transactions 20

# Simulate price movements
./aitbc-cli simulate price --price 100 --volatility 0.05 --timesteps 100

# Simulate network
./aitbc-cli simulate network --nodes 3 --network-delay 0.1 --failure-rate 0.05

# Simulate AI jobs
./aitbc-cli simulate ai-jobs --jobs 10 --models "text-generation,image-generation" --duration-range "30-300"

Configuration

Environment Variables

export AITBC_COORDINATOR_URL="http://localhost:8000"
export AITBC_API_KEY="your-api-key"
export AITBC_RPC_URL="http://localhost:8006"

Configuration File

The CLI uses configuration from /etc/aitbc/.env by default.

Command Line Options

# Output format
./aitbc-cli --output table|json|yaml|csv command

# Verbose output
./aitbc-cli --verbose command

# Debug mode
./aitbc-cli --debug command

# Test mode
./aitbc-cli --test-mode command

# Dry run
./aitbc-cli --dry-run command

# Custom timeout
./aitbc-cli --timeout 60 command

# Skip SSL verification (testing only)
./aitbc-cli --no-verify command

Service Integration

Service Endpoints

• Coordinator API: http://localhost:8000
• Exchange API: http://localhost:8001
• Blockchain RPC: http://localhost:8006
• Ollama: http://localhost:11434

Health Checks

# Check all services
curl -s http://localhost:8000/health
curl -s http://localhost:8001/api/health
curl -s http://localhost:8006/health
curl -s http://localhost:11434/api/tags

Examples

Basic Workflow

# 1. Create wallet
./aitbc-cli create --name my-wallet --password my-password

# 2. Fund wallet (from existing wallet)
./aitbc-cli send --from genesis-ops --to my-wallet --amount 1000 --password 123

# 3. Submit AI job
./aitbc-cli ai-submit --wallet my-wallet --type inference --prompt "Generate a landscape image" --payment 50

# 4. Check job status
./aitbc-cli ai-ops --action status --job-id latest

# 5. Get results
./aitbc-cli ai-ops --action results --job-id latest

Marketplace Operations

# 1. Create service listing
./aitbc-cli marketplace --action create --name "AI Image Generation" --price 100 --description "High-quality image generation service" --wallet provider-wallet

# 2. List available services
./aitbc-cli marketplace --action list

# 3. Bid on service
./aitbc-cli marketplace --action bid --service-id service-id --amount 120 --wallet customer-wallet

# 4. Accept bid
./aitbc-cli marketplace --action accept-bid --service-id service-id --bid-id bid-id --wallet provider-wallet

Simulation Examples

# Simulate blockchain with 100 blocks
./aitbc-cli simulate blockchain --blocks 100 --transactions 100 --delay 0.1

# Simulate price volatility
./aitbc-cli simulate price --price 100 --volatility 0.1 --timesteps 1000

# Simulate network failures
./aitbc-cli simulate network --nodes 5 --failure-rate 0.1 --network-delay 0.5

Troubleshooting

Common Issues

Command Not Found

# Check CLI installation
./aitbc-cli --version

# Check virtual environment
source venv/bin/activate

Service Connection Errors

# Check service status
systemctl status aitbc-coordinator-api.service
systemctl status aitbc-exchange-api.service
systemctl status aitbc-blockchain-node.service

# Check network connectivity
curl -s http://localhost:8000/health

Permission Errors

# Check file permissions
ls -la /opt/aitbc/aitbc-cli

# Fix permissions
chmod +x /opt/aitbc/aitbc-cli

Debug Mode

# Enable debug output
./aitbc-cli --debug --verbose command

# Test with mock data
./aitbc-cli --test-mode command

Development

Running Tests

# Run all tests
cd /opt/aitbc
source venv/bin/activate
python -m pytest cli/tests/ -v

# Run specific test
python -m pytest cli/tests/test_cli_comprehensive.py::TestSimulateCommand -v

# Run with coverage
python -m pytest cli/tests/ --cov=cli --cov-report=html

Adding New Commands

1. Create command file in cli/aitbc_cli/commands/
2. Import command in cli/core/main.py
3. Add tests in cli/tests/
4. Update documentation

Code Style

# Format code
black cli/

# Lint code
flake8 cli/

# Type checking
mypy cli/

API Reference

Command Options

Global Options

• --url: Override coordinator URL
• --api-key: Set API key
• --output: Set output format (table, json, yaml, csv)
• --verbose: Increase verbosity
• --debug: Enable debug mode
• --test-mode: Use test endpoints
• --dry-run: Show what would be done
• --timeout: Set request timeout
• --no-verify: Skip SSL verification

Command-Specific Options

Each command has specific options documented in the help:

./aitbc-cli command --help

Exit Codes

• 0: Success
• 1: General error
• 2: Command line error

Version History

v0.2.2 (Current)

• Unified CLI with 20+ commands
• Enhanced output formatting
• AI operations integration
• Marketplace functionality
• Resource management
• Simulation commands
• OpenClaw agent integration

v0.2.1

• Project consolidation to /opt/aitbc
• Enhanced service integration
• Improved error handling

v0.2.0

• Modular command structure
• Enhanced configuration management
• Performance improvements

v0.1.0

• Initial CLI implementation
• Basic wallet and blockchain operations

Support

For issues and questions:

1. Check troubleshooting section
2. Run with --debug --verbose for detailed output
3. Check service health status
4. Review logs in /var/log/aitbc/

Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Update documentation
6. Submit pull request