aitbc/docs/skills/aitbc-cli.md

name, description, category

name	description	category
aitbc-cli	Complete guide for using the AITBC CLI tool - wallet management, transactions, blockchain analytics, marketplace, AI jobs, mining, agent operations, simulations	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:

cd /opt/aitbc
./aitbc-cli [command] [options]

Step-by-Step Instructions

1. Wallet Management

Create Wallet

./aitbc-cli create --name <wallet_name> --password <password>

Example:

./aitbc-cli create --name my-wallet --password "securepassword123"

Result: Creates wallet with Ed25519 keypair, AES-256-GCM encryption, returns address

Import Wallet

./aitbc-cli import --name <wallet_name> --private-key <hex_key> --password <password>

Example:

./aitbc-cli import --name imported-wallet --private-key "abc123..." --password "securepassword123"

Export Wallet (Private Key)

./aitbc-cli export --name <wallet_name> --password <password>

Delete Wallet

./aitbc-cli delete --name <wallet_name>

Rename Wallet

./aitbc-cli rename --old <old_name> --new <new_name>

List Wallets

./aitbc-cli list --format [table|json]

Result: Lists all wallets from keystore or wallet daemon

---

2. Transaction Operations

Send Transaction

./aitbc-cli send \
  --from <wallet_name> \
  --to <recipient_address> \
  --amount <amount> \
  --fee <fee> \
  --password <password> \
  --rpc-url <rpc_url>

Example:

./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

./aitbc-cli balance --name <wallet_name> --rpc-url <rpc_url>

Example:

./aitbc-cli balance --name my-wallet --rpc-url http://localhost:8006

Result: Returns balance, nonce, address

Get Transaction History

./aitbc-cli transactions --name <wallet_name> --limit <limit> --format [table|json] --rpc-url <rpc_url>

Example:

./aitbc-cli transactions --name my-wallet --limit 10 --format table --rpc-url http://localhost:8006

---

3. Blockchain Analytics

Get Chain Information

./aitbc-cli chain --rpc-url <rpc_url>

Example:

./aitbc-cli chain --rpc-url http://localhost:8006

Result: Chain ID, height, hash, timestamp, proposer ID, supported chains

Get Network Status

./aitbc-cli network --rpc-url <rpc_url>

Result: Head block information, network health

Blockchain Analytics

./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:

./aitbc-cli analytics --type blocks --limit 10 --rpc-url http://localhost:8006

---

4. Mining Operations

Start Mining

./aitbc-cli mine start --wallet <wallet_name> --threads <threads> --rpc-url <rpc_url>

Example:

./aitbc-cli mine start --wallet my-wallet --threads 1 --rpc-url http://localhost:8006

Result: Mining started with specified wallet

Stop Mining

./aitbc-cli mine stop --rpc-url <rpc_url>

Get Mining Status

./aitbc-cli mine status --rpc-url <rpc_url>

Result: Mining active status, current height, blocks mined, rewards earned

---

5. Marketplace Operations

List Marketplace Items

./aitbc-cli marketplace --action list --rpc-url <rpc_url>

Alternative command:

./aitbc-cli market-list --rpc-url <rpc_url>

Result: List of available marketplace items

Create Marketplace Listing

./aitbc-cli marketplace \
  --action create \
  --name <item_name> \
  --price <price> \
  --description <description> \
  --wallet <wallet_name> \
  --rpc-url <rpc_url>

Alternative command:

./aitbc-cli market-create \
  --wallet <wallet_name> \
  --type <service_type> \
  --price <price_in_AIT> \
  --description <description> \
  --password <password> \
  --rpc-url <rpc_url>

Example:

./aitbc-cli market-create \
  --wallet my-wallet \
  --type "gpu-compute" \
  --price 100 \
  --description "GPU compute for AI training" \
  --password "securepassword123" \
  --rpc-url http://localhost:8006

Result: Returns listing ID, provider, price, status

Search Marketplace

./aitbc-cli marketplace --action search --name <search_term> --rpc-url <rpc_url>

List My Listings

./aitbc-cli marketplace --action my-listings --wallet <wallet_name> --rpc-url <rpc_url>

---

6. AI Compute Operations

Submit AI Job

./aitbc-cli ai-ops submit \
  --wallet <wallet_name> \
  --type <job_type> \
  --prompt <prompt> \
  --payment <payment> \
  --password <password> \
  --rpc-url <rpc_url>

Example:

./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

./aitbc-cli ai-ops status --job-id <job_id> --rpc-url <rpc_url>

---

7. Agent Operations

Create Agent

./aitbc-cli agent create \
  --name <agent_name> \
  --verification <basic|advanced> \
  --max-execution-time <seconds> \
  --max-cost-budget <amount>

Execute Agent

./aitbc-cli agent execute \
  --name <agent_name> \
  --priority [low|medium|high]

List Agents

./aitbc-cli agent list --status [active|completed|failed]

Note: Uses coordinator API at http://localhost:9001 for real agent discovery

Send Message to Agent

./aitbc-cli agent message \
  --agent <agent_address> \
  --message <message_content> \
  --wallet <wallet_name> \
  --password <password> \
  --rpc-url <rpc_url>

Example:

./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

./aitbc-cli agent messages --agent <agent_address> --rpc-url <rpc_url>

Result: Lists all messages sent to the agent from blockchain

Register Agent (via CLI)

# CLI method for agent registration
python3 cli/unified_cli.py agent register \
  --agent-id <agent_id> \
  --agent-type worker \
  --endpoint <endpoint> \
  --capabilities marketplace,messaging

Note: For API-based registration, see aitbc.md skill

---

8. Hermes Training Operations

Deploy Hermes Agent

./aitbc-cli hermes deploy --environment [dev|prod]

Monitor Hermes Agent

./aitbc-cli hermes monitor --agent-id <agent_id> --metrics [all|performance|cost]

Train Agent

./aitbc-cli hermes train \
  --train-action agent \
  --agent-id <agent_id> \
  --stage <stage_name> \
  --training-data <training_data_file>

Example:

./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

./aitbc-cli workflow create --name <workflow_name> --template [custom|standard]

Run Workflow

./aitbc-cli workflow run --name <workflow_name> --async-exec

---

10. Resource Operations

Check Resource Status

./aitbc-cli resource status --type [all|cpu|memory|storage]

Allocate Resources

./aitbc-cli resource allocate \
  --agent-id <agent_id> \
  --cpu <cores> \
  --memory <gb> \
  --duration <minutes>

Optimize Resources

./aitbc-cli resource optimize --target [all|cpu|memory] --agent-id <agent_id>

Benchmark Resources

./aitbc-cli resource benchmark --type [all|cpu|memory|network]

---

11. Simulation Operations

Simulate Blockchain

./aitbc-cli simulate blockchain \
  --blocks <number> \
  --transactions <per_block> \
  --delay <seconds>

Example:

./aitbc-cli simulate blockchain --blocks 10 --transactions 5 --delay 0.5

Result: Simulates block production with transactions, shows statistics

Simulate Wallets

./aitbc-cli simulate wallets \
  --wallets <number> \
  --balance <initial_balance> \
  --transactions <number> \
  --amount-range <min-max>

Example:

./aitbc-cli simulate wallets --wallets 5 --balance 1000 --transactions 20 --amount-range 1-100

Simulate Price

./aitbc-cli simulate price \
  --price <starting_price> \
  --volatility <percentage> \
  --timesteps <number> \
  --delay <seconds>

Example:

./aitbc-cli simulate price --price 100.0 --volatility 0.05 --timesteps 50 --delay 0.1

Simulate Network

./aitbc-cli simulate network \
  --nodes <number> \
  --network-delay <seconds> \
  --failure-rate <percentage>

Example:

./aitbc-cli simulate network --nodes 10 --network-delay 0.5 --failure-rate 0.1

Simulate AI Jobs

./aitbc-cli simulate ai-jobs \
  --jobs <number> \
  --models <model_list> \
  --duration-range <min-max_seconds>

Example:

./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

# 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

./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

# 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