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, and agent workflows.

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

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