docs: add aitbc-cli skill

- Created comprehensive skill for AITBC CLI tool at /opt/aitbc/skills/aitbc-cli/SKILL.md - Documents all CLI operations: wallet management, transactions, blockchain analytics, marketplace, AI jobs, mining, agent operations, simulations - Includes step-by-step instructions, examples, pitfalls, and quick reference - Focus on operational information, no changelog content - Skill ships with AITBC software repository
2026-05-08 20:44:57 +02:00
parent e9ec51b8d1
commit b3dcd87a9b
1 changed files with 617 additions and 0 deletions
--- a/skills/aitbc-cli/SKILL.md
+++ 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 <wallet_name> --password <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 <wallet_name> --private-key <hex_key> --password <password>
+```
+
+**Example:**
+```bash
+./aitbc-cli import --name imported-wallet --private-key "abc123..." --password "securepassword123"
+```
+
+#### Export Wallet (Private Key)
+```bash
+./aitbc-cli export --name <wallet_name> --password <password>
+```
+
+#### Delete Wallet
+```bash
+./aitbc-cli delete --name <wallet_name>
+```
+
+#### Rename Wallet
+```bash
+./aitbc-cli rename --old <old_name> --new <new_name>
+```
+
+#### 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 <wallet_name> \
+  --to <recipient_address> \
+  --amount <amount> \
+  --fee <fee> \
+  --password <password> \
+  --rpc-url <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 <wallet_name> --rpc-url <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 <wallet_name> --limit <limit> --format [table|json] --rpc-url <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 <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 <rpc_url>
+```
+
+**Result:** Head block information, network health
+
+#### Blockchain Analytics
+```bash
+./aitbc-cli analytics --type [blocks|supply|accounts] --limit <limit> --rpc-url <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 <wallet_name> --threads <threads> --rpc-url <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 <rpc_url>
+```
+
+#### Get Mining Status
+```bash
+./aitbc-cli mine status --rpc-url <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 <rpc_url>
+```
+
+**Result:** List of available marketplace items
+
+#### Create Marketplace Listing
+```bash
+./aitbc-cli marketplace \
+  --action create \
+  --name <item_name> \
+  --price <price> \
+  --description <description> \
+  --wallet <wallet_name> \
+  --rpc-url <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 <wallet_name> \
+  --type <job_type> \
+  --prompt <prompt> \
+  --payment <payment> \
+  --password <password> \
+  --rpc-url <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 <job_id> --rpc-url <rpc_url>
+```
+
+---
+
+### 7. Agent Operations
+
+#### Create Agent
+```bash
+./aitbc-cli agent create \
+  --name <agent_name> \
+  --verification <basic|advanced> \
+  --max-execution-time <seconds> \
+  --max-cost-budget <amount>
+```
+
+#### Execute Agent
+```bash
+./aitbc-cli agent execute \
+  --name <agent_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 <agent_address> \
+  --message <message_content> \
+  --wallet <wallet_name> \
+  --password <password> \
+  --rpc-url <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 <agent_address> --rpc-url <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 <agent_id> --metrics [all|performance|cost]
+```
+
+#### Train Agent
+```bash
+./aitbc-cli hermes train \
+  --train-action agent \
+  --agent-id <agent_id> \
+  --stage <stage_name> \
+  --training-data <training_data_file>
+```
+
+**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 <workflow_name> --template [custom|standard]
+```
+
+#### Run Workflow
+```bash
+./aitbc-cli workflow run --name <workflow_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 <agent_id> \
+  --cpu <cores> \
+  --memory <gb> \
+  --duration <minutes>
+```
+
+#### Optimize Resources
+```bash
+./aitbc-cli resource optimize --target [all|cpu|memory] --agent-id <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 <number> \
+  --transactions <per_block> \
+  --delay <seconds>
+```
+
+**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 <number> \
+  --balance <initial_balance> \
+  --transactions <number> \
+  --amount-range <min-max>
+```
+
+**Example:**
+```bash
+./aitbc-cli simulate wallets --wallets 5 --balance 1000 --transactions 20 --amount-range 1-100
+```
+
+#### Simulate Price
+```bash
+./aitbc-cli simulate price \
+  --price <starting_price> \
+  --volatility <percentage> \
+  --timesteps <number> \
+  --delay <seconds>
+```
+
+**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 <number> \
+  --network-delay <seconds> \
+  --failure-rate <percentage>
+```
+
+**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 <number> \
+  --models <model_list> \
+  --duration-range <min-max_seconds>
+```
+
+**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 <name> --password <password>
+./aitbc-cli list --format [table|json]
+./aitbc-cli balance --name <name>
+./aitbc-cli send --from <name> --to <address> --amount <amount> --password <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 <name> --threads 1
+./aitbc-cli mine status
+./aitbc-cli mine stop
+
+# Marketplace
+./aitbc-cli marketplace --action list
+./aitbc-cli marketplace --action create --name <name> --price <price>
+
+# AI Jobs
+./aitbc-cli ai-ops submit --wallet <name> --type inference --prompt <text> --payment <amount>
+
+# Agents
+./aitbc-cli agent list --status active
+./aitbc-cli agent message --agent <address> --message <text> --wallet <name> --password <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`