aitbc/docs/cli/CLICK_CLI.md

AITBC CLI Documentation

Overview

The AITBC CLI has a single entry point (aitbc-cli) that delegates to two command architectures:

1. Production CLI (Parser/Handler): Core blockchain operations using parser/handler architecture
2. Click-Based Commands: Agent-specific operations using Click framework

Single Entry Point

Location

• Entry point: /opt/aitbc/aitbc-cli → /opt/aitbc/cli/aitbc_cli.py
• Command groups: /opt/aitbc/cli/commands/

Usage

# Single entry point for all commands
aitbc-cli [OPTIONS] COMMAND [ARGS]...

# Get help
aitbc-cli --help
aitbc-cli [COMMAND] --help

Command Delegation

The main entry point automatically delegates commands based on type:

Production Commands (Parser/Handler):

• wallet, blockchain, account, messaging, network, market, ai, analytics, script, mining, system, economics, cluster, performance, security, compliance, simulate, agent, hermes-training, workflow, resource, genesis, pool-hub, bridge, contract

Click Commands (Agent Operations):

• agent, ipfs, oracle, swarm, arbitrage, validator, plugin, database, island, edge, ai, monitor, governance, staking, compliance

Available Commands

IPFS Commands

aitbc-cli ipfs upload --file <path> [--pin] [--name <name>]
aitbc-cli ipfs download <cid> [--output <path>]
aitbc-cli ipfs pin <cid>
aitbc-cli ipfs list

Oracle Commands

aitbc-cli oracle store --cid <cid> --price <price> [--description <desc>]
aitbc-cli oracle announce --cid <cid> --price <price>
aitbc-cli oracle listen --wallet <wallet>
aitbc-cli oracle retrieve <cid>
aitbc-cli oracle listings --wallet <wallet>

Agent Commands

# Main agent commands
aitbc-cli agent create --name <name> --description <desc>
aitbc-cli agent list [--type <type>] [--status <status>]
aitbc-cli agent execute <agent_id> --inputs <file>
aitbc-cli agent status <execution_id>

# Agent subcommands
aitbc-cli agent zk generate-proof --input <data> --circuit <circuit>
aitbc-cli agent zk verify-proof --proof <proof> --public-inputs <inputs>
aitbc-cli agent knowledge create --name <name>
aitbc-cli agent knowledge add-node --graph-id <id> --data <json>
aitbc-cli agent bounty create --title <title> --description <desc> --reward <amount>
aitbc-cli agent dispute file --title <title> --description <desc> --evidence <evidence>

Swarm Commands

aitbc-cli swarm create --name <name> --max-agents <count>
aitbc-cli swarm discover --swarm-id <id> [--capability <cap>]
aitbc-cli swarm add --swarm-id <id> --agent-id <agent>
aitbc-cli swarm distribute --swarm-id <id> --task <task>
aitbc-cli swarm status --swarm-id <id>

Architecture

Single Entry Point with Command Delegation

The main CLI entry point (aitbc-cli) automatically delegates commands based on type:

# In aitbc_cli.py
CLICK_COMMANDS = [
    'agent', 'ipfs', 'oracle', 'swarm', 'arbitrage', 'validator', 
    'plugin', 'database', 'island', 'edge', 'ai', 'monitor', 
    'governance', 'staking', 'compliance'
]

def main(argv=None):
    if argv and argv[0] in CLICK_COMMANDS:
        # Delegate to Click CLI
        from cli.click_cli import aitbc_click
        aitbc_click()
    else:
        # Delegate to unified CLI (parser/handler)
        from unified_cli import run_cli
        return run_cli(argv, globals())

Click Command Pattern

Click commands follow this pattern:

import click
from utils import output, error, success, warning

@click.group()
def command_group():
    """Command group description"""
    pass

@command_group.command()
@click.option("--option", required=True, help="Option description")
@click.argument("argument")
def subcommand(option: str, argument: str):
    """Subcommand description"""
    try:
        # Implementation logic
        result = {"status": "success", "data": {...}}
        output(result)
    except Exception as e:
        error(f"Failed: {e}")

Registering New Commands

To add a new Click command group:

1. Create file in /opt/aitbc/cli/commands/<command>.py
2. Add command to CLICK_COMMANDS list in /opt/aitbc/cli/aitbc_cli.py
3. Import and register in /opt/aitbc/cli/click_cli.py

For production parser/handler commands, use the standard parser/handler pattern in /opt/aitbc/cli/parsers/ and /opt/aitbc/cli/handlers/.

Integration with Agent SDK

Agent SDK methods call Click CLI commands via subprocess:

from aitbc_agent.command_executor import CommandExecutor

executor = CommandExecutor("/opt/aitbc/aitbc-cli")
result = executor.execute_command("ipfs", ["upload", "--file", "path"])

Implementation Status

Implemented CLI Commands

• ✅ IPFS (upload, download, pin, list)
• ✅ Oracle (store, announce, listen, retrieve, listings)
• ✅ Agent (create, list, execute, status)
• ✅ Agent zk (generate-proof, verify-proof, create-receipt)
• ✅ Agent knowledge (create, add-node)
• ✅ Agent bounty (create, list)
• ✅ Agent dispute (file, vote)
• ✅ Swarm (create, discover, add, distribute, status)
• ✅ Arbitrage (analyze, find, execute, status, performance)
• ✅ Validator (init, status, deregister, slashing)
• ✅ Plugin (publish, list, install, uninstall)
• ✅ Database (init, query, backup, restore)
• ✅ Island (create, join, leave, bridge)
• ✅ Edge (init, status, list, configure)
• ✅ AI (submit, list-ai-power, trade-ai-power, reputation)
• ✅ Monitor (start, stop, status, alerts)
• ✅ Governance (vote)
• ✅ Staking (manage)
• ✅ Compliance (check, report)
• ✅ Cross-chain (transfer, list, swaps)

Testing

# Test CLI entry point
aitbc-cli --help
aitbc-cli ipfs --help
aitbc-cli agent --help
aitbc-cli agent zk --help

# Test specific command
aitbc-cli agent zk generate-proof --input test --circuit circuit1

Notes

• The CLI uses a single entry point (aitbc-cli) for all commands
• Production commands (wallet, blockchain, etc.) use parser/handler architecture
• Agent-specific commands (agent, ipfs, oracle, etc.) use Click framework
• Agent SDK methods internally call aitbc-cli commands via subprocess
• Commands are automatically delegated based on the command group