diff --git a/skills/aitbc-cli/SKILL.md b/skills/aitbc-cli/SKILL.md new file mode 100644 index 00000000..05de8c3b --- /dev/null +++ b/skills/aitbc-cli/SKILL.md @@ -0,0 +1,617 @@ +--- +name: aitbc-cli +description: Complete guide for using the AITBC CLI tool - wallet management, transactions, blockchain analytics, marketplace, AI jobs, mining, agent operations, simulations +category: software-development +--- + +# AITBC CLI Tool Skill + +Complete guide for Hermes agent to use the AITBC CLI tool (`/opt/aitbc/aitbc-cli`) for blockchain operations, wallet management, marketplace, AI jobs, mining, and simulations. **This skill ships with AITBC software repository.** + +## Trigger Conditions + +Load this skill when: +- User asks to use "aitbc-cli" or "AITBC CLI" +- Need to manage wallets (create, import, export, delete, rename, list) +- Need to send transactions or check balances +- Need blockchain analytics or network status +- Need marketplace operations (listings, create, buy) +- Need AI compute job operations +- Need mining operations (start, stop, status) +- Need agent operations (create, execute, list, message) +- Need to run simulations (blockchain, wallets, price, network, AI jobs) + +## Prerequisites + +- AITBC software installed at `/opt/aitbc` +- Python 3.13+ with required dependencies +- Blockchain RPC service running (default: `http://localhost:8006`) +- Wallet keystore directory: `/var/lib/aitbc/keystore/` + +## CLI Location + +**Main CLI:** `/opt/aitbc/aitbc-cli` + +**Usage:** +```bash +cd /opt/aitbc +./aitbc-cli [command] [options] +``` + +## Step-by-Step Instructions + +### 1. Wallet Management + +#### Create Wallet +```bash +./aitbc-cli create --name --password +``` + +**Example:** +```bash +./aitbc-cli create --name my-wallet --password "securepassword123" +``` + +**Result:** Creates wallet with Ed25519 keypair, AES-256-GCM encryption, returns address + +#### Import Wallet +```bash +./aitbc-cli import --name --private-key --password +``` + +**Example:** +```bash +./aitbc-cli import --name imported-wallet --private-key "abc123..." --password "securepassword123" +``` + +#### Export Wallet (Private Key) +```bash +./aitbc-cli export --name --password +``` + +#### Delete Wallet +```bash +./aitbc-cli delete --name +``` + +#### Rename Wallet +```bash +./aitbc-cli rename --old --new +``` + +#### List Wallets +```bash +./aitbc-cli list --format [table|json] +``` + +**Result:** Lists all wallets from keystore or wallet daemon + +--- + +### 2. Transaction Operations + +#### Send Transaction +```bash +./aitbc-cli send \ + --from \ + --to \ + --amount \ + --fee \ + --password \ + --rpc-url +``` + +**Example:** +```bash +./aitbc-cli send \ + --from my-wallet \ + --to ait1abc123... \ + --amount 100.0 \ + --fee 10.0 \ + --password "securepassword123" \ + --rpc-url http://localhost:8006 +``` + +**Result:** Returns transaction hash + +#### Check Balance +```bash +./aitbc-cli balance --name --rpc-url +``` + +**Example:** +```bash +./aitbc-cli balance --name my-wallet --rpc-url http://localhost:8006 +``` + +**Result:** Returns balance, nonce, address + +#### Get Transaction History +```bash +./aitbc-cli transactions --name --limit --format [table|json] --rpc-url +``` + +**Example:** +```bash +./aitbc-cli transactions --name my-wallet --limit 10 --format table --rpc-url http://localhost:8006 +``` + +--- + +### 3. Blockchain Analytics + +#### Get Chain Information +```bash +./aitbc-cli chain --rpc-url +``` + +**Example:** +```bash +./aitbc-cli chain --rpc-url http://localhost:8006 +``` + +**Result:** Chain ID, height, hash, timestamp, proposer ID, supported chains + +#### Get Network Status +```bash +./aitbc-cli network --rpc-url +``` + +**Result:** Head block information, network health + +#### Blockchain Analytics +```bash +./aitbc-cli analytics --type [blocks|supply|accounts] --limit --rpc-url +``` + +**Types:** +- `blocks`: Recent blocks analytics +- `supply`: Total supply information +- `accounts`: Account statistics + +**Example:** +```bash +./aitbc-cli analytics --type blocks --limit 10 --rpc-url http://localhost:8006 +``` + +--- + +### 4. Mining Operations + +#### Start Mining +```bash +./aitbc-cli mine start --wallet --threads --rpc-url +``` + +**Example:** +```bash +./aitbc-cli mine start --wallet my-wallet --threads 1 --rpc-url http://localhost:8006 +``` + +**Result:** Mining started with specified wallet + +#### Stop Mining +```bash +./aitbc-cli mine stop --rpc-url +``` + +#### Get Mining Status +```bash +./aitbc-cli mine status --rpc-url +``` + +**Result:** Mining active status, current height, blocks mined, rewards earned + +--- + +### 5. Marketplace Operations + +#### List Marketplace Items +```bash +./aitbc-cli marketplace --action list --rpc-url +``` + +**Result:** List of available marketplace items + +#### Create Marketplace Listing +```bash +./aitbc-cli marketplace \ + --action create \ + --name \ + --price \ + --description \ + --wallet \ + --rpc-url +``` + +**Example:** +```bash +./aitbc-cli marketplace \ + --action create \ + --name "AI Compute Hour" \ + --price 100 \ + --description "GPU compute for AI training" \ + --wallet my-wallet \ + --rpc-url http://localhost:8006 +``` + +--- + +### 6. AI Compute Operations + +#### Submit AI Job +```bash +./aitbc-cli ai-ops submit \ + --wallet \ + --type \ + --prompt \ + --payment \ + --password \ + --rpc-url +``` + +**Example:** +```bash +./aitbc-cli ai-ops submit \ + --wallet my-wallet \ + --type "inference" \ + --prompt "Analyze this data" \ + --payment 50 \ + --password "securepassword123" \ + --rpc-url http://localhost:8006 +``` + +**Result:** Job ID, estimated time, payment amount + +#### Check AI Job Status +```bash +./aitbc-cli ai-ops status --job-id --rpc-url +``` + +--- + +### 7. Agent Operations + +#### Create Agent +```bash +./aitbc-cli agent create \ + --name \ + --verification \ + --max-execution-time \ + --max-cost-budget +``` + +#### Execute Agent +```bash +./aitbc-cli agent execute \ + --name \ + --priority [low|medium|high] +``` + +#### List Agents +```bash +./aitbc-cli agent list --status [active|completed|failed] +``` + +**Note:** Uses coordinator API at `http://localhost:9001` for real agent discovery + +#### Send Message to Agent +```bash +./aitbc-cli agent message \ + --agent \ + --message \ + --wallet \ + --password \ + --rpc-url +``` + +**Example:** +```bash +./aitbc-cli agent message \ + --agent ait1abc123... \ + --message "Hello agent" \ + --wallet my-wallet \ + --password "securepassword123" \ + --rpc-url http://localhost:8006 +``` + +**Result:** Message sent via blockchain transaction, returns transaction hash + +#### Retrieve Agent Messages +```bash +./aitbc-cli agent messages --agent --rpc-url +``` + +**Result:** Lists all messages sent to the agent from blockchain + +--- + +### 8. Hermes Training Operations + +#### Deploy Hermes Agent +```bash +./aitbc-cli hermes deploy --environment [dev|prod] +``` + +#### Monitor Hermes Agent +```bash +./aitbc-cli hermes monitor --agent-id --metrics [all|performance|cost] +``` + +#### Train Agent +```bash +./aitbc-cli hermes train \ + --train-action agent \ + --agent-id \ + --stage \ + --training-data +``` + +**Example:** +```bash +./aitbc-cli hermes train \ + --train-action agent \ + --agent-id hermes-001 \ + --stage stage1_foundation \ + --training-data /opt/aitbc/docs/agent-training/stage1_foundation.json +``` + +**Note:** Executes training operations via hermes agent with allowlist enabled + +--- + +### 9. Workflow Operations + +#### Create Workflow +```bash +./aitbc-cli workflow create --name --template [custom|standard] +``` + +#### Run Workflow +```bash +./aitbc-cli workflow run --name --async-exec +``` + +--- + +### 10. Resource Operations + +#### Check Resource Status +```bash +./aitbc-cli resource status --type [all|cpu|memory|storage] +``` + +#### Allocate Resources +```bash +./aitbc-cli resource allocate \ + --agent-id \ + --cpu \ + --memory \ + --duration +``` + +#### Optimize Resources +```bash +./aitbc-cli resource optimize --target [all|cpu|memory] --agent-id +``` + +#### Benchmark Resources +```bash +./aitbc-cli resource benchmark --type [all|cpu|memory|network] +``` + +--- + +### 11. Simulation Operations + +#### Simulate Blockchain +```bash +./aitbc-cli simulate blockchain \ + --blocks \ + --transactions \ + --delay +``` + +**Example:** +```bash +./aitbc-cli simulate blockchain --blocks 10 --transactions 5 --delay 0.5 +``` + +**Result:** Simulates block production with transactions, shows statistics + +#### Simulate Wallets +```bash +./aitbc-cli simulate wallets \ + --wallets \ + --balance \ + --transactions \ + --amount-range +``` + +**Example:** +```bash +./aitbc-cli simulate wallets --wallets 5 --balance 1000 --transactions 20 --amount-range 1-100 +``` + +#### Simulate Price +```bash +./aitbc-cli simulate price \ + --price \ + --volatility \ + --timesteps \ + --delay +``` + +**Example:** +```bash +./aitbc-cli simulate price --price 100.0 --volatility 0.05 --timesteps 50 --delay 0.1 +``` + +#### Simulate Network +```bash +./aitbc-cli simulate network \ + --nodes \ + --network-delay \ + --failure-rate +``` + +**Example:** +```bash +./aitbc-cli simulate network --nodes 10 --network-delay 0.5 --failure-rate 0.1 +``` + +#### Simulate AI Jobs +```bash +./aitbc-cli simulate ai-jobs \ + --jobs \ + --models \ + --duration-range +``` + +**Example:** +```bash +./aitbc-cli simulate ai-jobs --jobs 20 --models "llama2,mistral,gemma" --duration-range 30-300 +``` + +--- + +## Default Configuration + +**Default RPC URL:** `http://localhost:8006` + +**Default Keystore Directory:** `/var/lib/aitbc/keystore/` + +**Default Wallet Daemon URL:** `http://localhost:8003` + +**CLI Version:** 2.1.0 + +--- + +## Authentication + +### Wallet Password +- Required for: create, import, export, send, ai-ops submit, agent message +- Can be provided via `--password` or `--password-file` +- Genesis password location: `/var/lib/aitbc/keystore/.genesis_password` + +### Password File Usage +```bash +# Using password file +./aitbc-cli send --from my-wallet --to ait1abc... --amount 100 --password-file /var/lib/aitbc/keystore/.genesis_password +``` + +--- + +## Chain ID Handling + +**Auto-Detection:** CLI automatically detects chain ID from blockchain RPC health endpoint + +**Override:** Use `--chain-id` to override auto-detection +```bash +./aitbc-cli --chain-id ait-mainnet [command] +``` + +--- + +## Pitfalls & Common Errors + +### 1. Wallet Not Found +**Error:** `Wallet 'wallet_name' not found` +**Fix:** Check wallet name spelling, verify keystore directory + +### 2. Invalid Password +**Error:** `Error decrypting wallet` +**Fix:** Verify password, check password file permissions + +### 3. Invalid Address +**Error:** `Invalid recipient address` +**Fix:** Verify address format (starts with `ait1`) + +### 4. Insufficient Balance +**Error:** Transaction failed (insufficient balance) +**Fix:** Check wallet balance before sending + +### 5. RPC Connection Failed +**Error:** `Network error` +**Fix:** Verify blockchain RPC service is running, check RPC URL + +### 6. Chain ID Mismatch +**Error:** Transaction rejected (wrong chain) +**Fix:** Use `--chain-id` to specify correct chain or verify auto-detection + +### 7. Nonce Issues +**Error:** Transaction rejected (invalid nonce) +**Fix:** CLI automatically fetches actual nonce from blockchain + +### 8. Private Key Format +**Error:** `Invalid private key` +**Fix:** Ensure private key is valid hex string (64 hex characters for Ed25519) + +### 9. Keystore Encryption +**Error:** `Unsupported cipher` +**Fix:** CLI supports AES-256-GCM (blockchain-node standard) and Fernet (scripts/utils standard) + +### 10. Agent Registration Required +**Error:** Agent operations fail +**Fix:** Register agent via coordinator before using agent commands + +--- + +## Quick Reference + +```bash +# Wallet Management +./aitbc-cli create --name --password +./aitbc-cli list --format [table|json] +./aitbc-cli balance --name +./aitbc-cli send --from --to
--amount --password + +# Blockchain +./aitbc-cli chain --rpc-url http://localhost:8006 +./aitbc-cli network --rpc-url http://localhost:8006 +./aitbc-cli analytics --type blocks --limit 10 + +# Mining +./aitbc-cli mine start --wallet --threads 1 +./aitbc-cli mine status +./aitbc-cli mine stop + +# Marketplace +./aitbc-cli marketplace --action list +./aitbc-cli marketplace --action create --name --price + +# AI Jobs +./aitbc-cli ai-ops submit --wallet --type inference --prompt --payment + +# Agents +./aitbc-cli agent list --status active +./aitbc-cli agent message --agent
--message --wallet --password + +# Simulations +./aitbc-cli simulate blockchain --blocks 10 --transactions 5 +./aitbc-cli simulate wallets --wallets 5 --balance 1000 +./aitbc-cli simulate price --price 100 --volatility 0.05 +``` + +--- + +## Status + +**AITBC CLI Tool: FULLY OPERATIONAL** + +- Version: 2.1.0 +- All wallet operations working +- Blockchain analytics functional +- Marketplace operations supported +- AI job submission available +- Mining operations operational +- Agent operations with coordinator integration +- Simulation tools for testing and development +- **This skill ships with AITBC software repository** + +--- + +**Generated by:** Hermes Instructor (localhost) +**Date:** 2026-05-08 +**Purpose:** Single comprehensive skill for AITBC CLI tool operations +**Location:** `/opt/aitbc/skills/aitbc-cli/SKILL.md`