CLI for AI Agents

The BitBadges CLI is the recommended interface for AI agents, bots, and automated systems. Start by installing the chain binary + CLI via curl -fsSL https://install.bitbadges.io | sh — that's the canonical entrypoint for every harness covered below.

The CLI provides structured JSON output, pipe-friendly input, and LLM-consumable command discovery — everything an agent needs without writing TypeScript.

Claude Code users: after the CLI install above, you can optionally layer the BitBadges plugin on top for auto-wired MCP and 8 workflow skills that route Claude to the right CLI / MCP / docs surface (/plugin install bitbadges). The plugin is a convenience layer; everything on this page works with or without it.

Why CLI for Agents?

Structured JSON output — every command returns parseable JSON
--help-json — outputs the full command tree as structured JSON, perfect for LLM tool discovery
--dry-run — simulate any API call without side effects
Pipe-friendly — accepts stdin (-), file paths (@file.json), and inline JSON
Self-documenting — bb dev docs all dumps the entire documentation
No build step — no TypeScript compilation, no bundling, just install and run

Quick Setup for Agents

# 1. Install everything
curl -fsSL https://install.bitbadges.io | sh

# 2. Configure API key
bb settings set apiKey YOUR_KEY

# 3. Verify
bb doctor

Deprecation banner — agent-relevant. If your harness invokes legacy forms (bb cli <subcmd>, bitbadges-cli sign-with-browser, bitbadges-cli gen-tx-payload, the per-utility top-level names that moved under bb account / bb dev / bb settings), each call prints a one-line deprecation banner to stderr during the migration window. Stdout (the JSON envelope) is unaffected. Set BB_QUIET=1 in the agent's environment if banner noise is breaking line-based stderr parsers — the same flag also suppresses every command's auto-review commentary. The release after the migration window hard-fails the old forms; update prompts and scripts to the short form ahead of that cutover.

Heads up — API key vs. session. The API key is required on every indexer call but is the app scope. Anything that mutates an account, manages keys, or publishes signed data also needs a user scope: a session cookie obtained via auth login. The CLI is wallet-agnostic — pair it with bb sign-arbitrary for fully headless Cosmos signing, or paste in a signature from any external wallet.

Agent Workflow: Query, Review, Transact

Step 1: Discover available commands

# Get full command tree as JSON (for LLM tool discovery)
bb --help-json

# List all API route groups
bb api --help

# List routes in a specific group
bb api tokens --help

Step 2: Query data

# Get a collection
bb api tokens get-collection 1

# Check a balance
bb api tokens get-balance --body '{"collectionId":"1","address":"bb1..."}'

# Look up an account
bb api accounts get-account --body '{"address":"bb1..."}'

# Search
bb api misc search --body '{"query":"my-token"}'

Step 3: Review and audit

# Review a transaction before broadcasting
bb check tx.json

# Get human-readable explanation
bb explain tx.json

# Review a live collection
bb check 42 --testnet

# Interpret what a collection does
bb explain 42

Step 4: Browse docs and skills

# Dump full docs for context
bb dev docs all

# Browse a specific topic
bb dev docs learn/approvals

# List available builder skills
bb dev skills

# Get instructions for building a specific token type
bb dev skills smart-token

Step 5: Sign and broadcast (with chain binary)

# Create a key for the agent
bb keys add agent-wallet

# Sign and broadcast a transaction
bb tx tokenization create-collection ./collection.json \
  --from agent-wallet --chain-id bitbadges-1 \
  --node https://lcd.bitbadges.io:443 \
  --gas auto --gas-adjustment 1.5 --fees 10000ubadge

# Or broadcast via the API
bb api tx broadcast-tx --body @signed-tx.json

Step 6: Authenticate for `Full Access` API routes

Most read-only API routes work with just the API key, but anything that mutates an account or publishes signed data needs a session cookie. The CLI ships a wallet-agnostic three-step flow that pairs cleanly with the chain binary's offline signer:

# 1. Fetch a challenge (saves the nonce cookie locally for step 3)
MSG=$(bb auth challenge --address $(bb keys show agent-wallet -a) | jq -r .data.message)

# 2. Sign offline with the chain binary
SIG_JSON=$(bb sign-arbitrary agent-wallet "$MSG")

# 3. Post the signature — stores the session under ~/.bitbadges/auth.json
bb auth login \
  --address    "$(echo "$SIG_JSON" | jq -r .address)" \
  --signature  "$(echo "$SIG_JSON" | jq -r .signature)" \
  --public-key "$(echo "$SIG_JSON" | jq -r .pubKey)" \
  --message    "$MSG"

# 4. Make Full Access requests by adding --with-session
bb api accounts get-account --body '{"address":"bb1..."}' --with-session

Multi-account, multi-network. Full reference: Auth Commands.

Combining with BitBadges Builder Tools

For AI assistants that speak MCP (Claude, Cursor, etc.), the BitBadges Builder Tools provide 50+ higher-level tools for building token collections. The CLI and builder tools are complementary:

Use Case

Tool

Query data, browse docs, review transactions

CLI (bb)

Build token collections with guided workflows

BitBadges Builder Tools

Sign and broadcast transactions

Chain binary (bb or bitbadgeschaind) or SDK Signing Client

Key management

Chain binary (bb keys ...)

Example: Fully Automated Agent Script

#!/bin/bash
# Agent that checks a balance and conditionally transfers tokens

COLLECTION_ID=1
ADDRESS="bb1..."
THRESHOLD=10

# Query current balance
BALANCE=$(bb api tokens get-balance \
  --body "{\"collectionId\":\"$COLLECTION_ID\",\"address\":\"$ADDRESS\"}" \
  --condensed)

# Parse and decide — bb api emits the envelope; the body lives at .data
AMOUNT=$(echo "$BALANCE" | jq -r '.data.balances[0].amount // "0"')

if [ "$AMOUNT" -lt "$THRESHOLD" ]; then
  echo "Balance $AMOUNT below threshold $THRESHOLD, minting..."

  # Review the transaction first
  bb check ./mint-tx.json --testnet

  # If review passes, broadcast
  bb tx tokenization transfer-tokens ./mint-tx.json \
    --from agent-wallet --chain-id bitbadges-2 \
    --node https://lcd-testnet.bitbadges.io:443 \
    --gas auto --fees 10000ubadge
fi