agcli-bittensor 0.1.0

Python bindings for the agcli Bittensor SDK

agcli — Rust CLI + SDK for Bittensor

Agents first, fast, safe Rust toolkit for the Bittensor network.

Install

cargo install --git https://github.com/unarbos/agcli

Quick Examples

# Check balance
agcli balance --address 5Gx...

# List subnets as JSON
agcli --output json subnet list

# Stake TAO with slippage protection
agcli stake add --amount 10 --netuid 1 --max-slippage 2.0 --password p --yes

# Atomic commit-reveal weights
agcli weights commit-reveal --netuid 1 --weights "0:100,1:200" --wait

# Live subnet monitoring (JSON streaming)
agcli subnet monitor --netuid 97 --json

# Local development — zero cost, instant feedback
agcli localnet scaffold

Every command supports --output json|csv, --yes (skip prompts), --batch (hard-error mode), and --dry-run (preview). Full non-interactive operation for AI agents.

Documentation

Resource	Description
docs/why-agcli.md	Why agcli? Comparison with btcli and the Bittensor Python SDK
docs/llm.txt	Agent/LLM reference — quick-ref card + full command reference
docs/commands/	Per-command deep dives — on-chain behavior, pallet refs, storage keys, events, errors
docs/tutorials/	Step-by-step guides: getting started, staking, validator, subnet builder, agent automation
docs/faq.md	Beyond agcli — miners, Yuma math, picking subnets, validator↔miner protocols, subnet codebases
docs/hyperparameters.md	Complete reference for all ~32 sudo-settable subnet hyperparameters — what each does, defaults, interactions
docs/philosophy.md	Subnet design philosophy, incentive patterns, trust model

SDK Usage

[dependencies]
agcli = { git = "https://github.com/unarbos/agcli", default-features = false, features = ["sdk-only"] }

use agcli::{Client, Wallet, Balance};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Client::connect("wss://entrypoint-finney.opentensor.ai:443").await?;
    let balance = client.get_balance_ss58("5Gx...").await?;
    let subnets = client.get_all_subnets().await?;
    let metagraph = client.get_metagraph(1.into()).await?;
    Ok(())
}

Python SDK

Install the PyO3 extension (Rust SDK underneath) from the repo:

cd python
uv pip install -e ".[dev]"

import asyncio
from agcli import AsyncClient, Wallet, Balance, NetUid, Network

async def main() -> None:
    client = await AsyncClient.connect_network(Network.finney())
    subnets = await client.get_all_subnets()
    metagraph = await client.get_metagraph(NetUid(1))

asyncio.run(main())

Wallet operations are synchronous; chain queries use asyncio. The native agcli CLI binary is installed separately via cargo install.

Architecture

agcli/
├── src/
│   ├── main.rs              # CLI entry point
│   ├── lib.rs               # SDK re-exports (Client, Wallet, Balance, Config)
│   ├── config.rs            # Persistent config (~/.agcli/config.toml)
│   ├── error.rs             # Error classification + exit codes
│   ├── events.rs            # Real-time block/event subscription
│   ├── live.rs              # Live polling with delta tracking
│   ├── chain/
│   │   ├── mod.rs           # Client: connection, retry, 40+ queries + extrinsics
│   │   ├── queries.rs       # Chain query methods
│   │   ├── extrinsics.rs    # Transaction builders
│   │   └── rpc_types.rs     # Type conversions
│   ├── cli/
│   │   ├── mod.rs           # Clap parser: 20 command groups, 90+ subcommands
│   │   ├── commands.rs      # Main dispatcher
│   │   ├── helpers.rs       # Shared CLI helpers
│   │   ├── subnet_cmds.rs   # Subnet operations
│   │   ├── view_cmds.rs     # View/query handlers
│   │   ├── stake_cmds.rs    # Staking operations
│   │   ├── weights_cmds.rs  # Weight setting + commit-reveal
│   │   ├── wallet_cmds.rs   # Wallet management
│   │   ├── block_cmds.rs    # Block explorer
│   │   ├── network_cmds.rs  # Network queries + commitment commands
│   │   ├── localnet_cmds.rs # Local chain lifecycle + scaffold
│   │   ├── admin_cmds.rs    # AdminUtils sudo hyperparam setters
│   │   └── system_cmds.rs   # Config, proxy, delegate, identity
│   ├── localnet.rs           # SDK: Docker chain start/stop/status/reset/logs
│   ├── admin.rs              # SDK: 13 AdminUtils functions + raw_admin_call
│   ├── scaffold.rs           # SDK: Declarative test environment orchestration
│   ├── wallet/              # Key management (Python wallet compat)
│   ├── types/               # Balance, NeuronInfo, SubnetInfo, etc.
│   ├── queries/             # Cache layer (Moka + disk)
│   ├── extrinsics/          # Weight hashing, MEV shield
│   └── utils/               # Explain, format, POW solver
├── docs/
│   ├── llm.txt              # Agent-optimized reference
│   ├── commands/             # 24 per-command docs
│   └── tutorials/            # 5 step-by-step guides
├── examples/
│   └── scaffold.toml         # Example scaffold configuration
├── tests/                    # Integration tests (+ `cli_test_modules/`, `helpers_test_modules/`, `e2e_modules/`)
├── build.rs                  # Compile-time chain metadata fetch
└── Cargo.toml

Building

Requires Rust 1.75+ and network access (fetches chain metadata at build time):

git clone https://github.com/unarbos/agcli && cd agcli && cargo build --release

License

MIT