# 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](/for-developers/ai-agents/claude-code-plugin.md) 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 ```bash # 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 `, `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`](/for-developers/cli/auth-commands.md). 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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) ```bash # 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: ```bash # 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](/for-developers/cli/auth-commands.md). ## Combining with BitBadges Builder Tools For AI assistants that speak MCP (Claude, Cursor, etc.), the [BitBadges Builder Tools](/for-developers/ai-agents/builder-tools.md) 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 ```bash #!/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 ``` ## Further Reading * [Bot Examples](/for-developers/ai-agents/bot-examples.md) — TypeScript bot patterns * [Agent Spending Authorization](/for-developers/ai-agents/agent-spending-authorization.md) — on-chain spending limits for agents * [BitBadges Builder Tools](/for-developers/ai-agents/builder-tools.md) — 50+ tools for AI assistants * [Claims for Agents](/for-developers/ai-agents/claims-for-agents.md) — automated minting via claims --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bitbadges.io/for-developers/cli/for-ai-agents.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.