CLI

The bb CLI builds, inspects, signs, and broadcasts BitBadges transactions and calls the BitBadges API from the terminal. This page covers install, the command groups, settings, and health checks.

Agents should start with CLI Automation, choose a standard, and use the main-wallet payment flow when a human signs each request. The installed --help-json tree is the syntax authority; the standard pages explain the state and accounting rules behind those commands.

Install#

curl -fsSL https://install.bitbadges.io | sh
bb version
bb doctor

The one-liner installs two binaries:

bb is the only name used in these docs. bitbadgeschaind is the canonical binary name and is accepted everywhere bb is.

Installer options:

curl -fsSL https://install.bitbadges.io | sh -s -- --version v35          # pin a release
curl -fsSL https://install.bitbadges.io | sh -s -- --install-dir ~/.local/bin
curl -fsSL https://install.bitbadges.io | sh -s -- --no-sudo
curl -fsSL https://install.bitbadges.io | sh -s -- --testnet             # testnet binary (testnet is offline)

SDK CLI Only#

If you do not need the chain node binary:

bun install -g bitbadges     # or: npm install -g bitbadges
bitbadges-cli --help

The npm package bitbadges ships three bins: bitbadges and bitbadges-cli (the CLI, same file) and bitbadges-builder (the MCP builder tools server, see Set Up Your AI). SDK-owned commands such as bb build and bb api run as bitbadges-cli build and bitbadges-cli api. Native chain commands such as query, keys, and sign-arbitrary still require bitbadgeschaind; the SDK-only install does not provide them.

Chain Binary from Source#

git clone https://github.com/BitBadges/bitbadgeschain.git
cd bitbadgeschain
make build-mainnet-darwin/arm64   # or build-mainnet-linux/amd64, build-mainnet-linux/arm64, build-mainnet-darwin/amd64, build-mainnet-windows/amd64

Requires the Go version in go.mod (1.26 at time of writing). Pre-built binaries are on the releases page. Use the binary version that matches the current chain height; the chain upgrades periodically.

Claude Code Plugin#

Claude Code users can add the Claude Code Plugin on top of this install. It wires the MCP server and adds workflow skills. It does not replace the CLI.

Command Groups#

bb --help prints the commands in groups so you can tell which binary owns a verb.

bb --help
bb --help-json | jq '.commands[] | .name'   # full SDK command tree as JSON

Deprecated Forms#

Old forms still resolve for one release and print a one-line [bb] DEPRECATED: banner on stderr that names the new form. The release after the window removes them.

BB_QUIET=1 or --quiet suppresses the banner. Do not write new scripts or agent prompts against the old forms.

Output Envelope#

Every data-emitting SDK verb prints one JSON envelope on stdout and human commentary on stderr.

bb api tokens get-collection 1 | jq .data
bb explain tx.json --quiet | jq -r .data.fullText

{ "ok": true, "data": {}, "warnings": [], "hint": "optional", "meta": {}, "error": null }

bb build adds a meta sidecar with validation, review, simulate, and resolved-metadata reports next to the message in data. hint is set on common failures (auth rejected, 401/403, insufficient funds on deploy, tx wait timeout).

Inputs are uniform: a file path, @file.json, inline JSON, or - for stdin.

Settings#

bb settings set apiKey "$BITBADGES_API_KEY"
bb settings show
bb settings unset apiKeyTestnet

Config lives at ~/.bitbadges/config.json (or $BITBADGES_CONFIG_DIR/config.json). Get an API key at bitbadges.io/developer.

Environment Variables#

Network Flags#

Every SDK verb that reaches the network accepts the same flags.

Resolution order for the API key: --api-key > network-specific env var > BITBADGES_API_KEY > network-specific config key > apiKey in config. For the base URL: --url > --local > --testnet > BITBADGES_API_URL > config url > https://api.bitbadges.io.

Doctor#

bb doctor
bb doctor --with-preview
bb doctor --condensed | jq '.data.checks[] | select(.status != "pass")'

Probes, in order: Node version (18 or newer), SDK package and version, config file, API key for the resolved network (pings the simulate endpoint), MCP stdio bin, persisted sessions parse, and with --with-preview a preview upload and fetch round trip that asserts byte equality. Each probe reports pass, fail, warn, or skip. The exit code is non-zero only on hard failures.

Session#

Builder sessions from bb dev tools call --session <id> persist under ~/.bitbadges/sessions/<id>.json.

bb session list
bb session show demo
bb session reset demo

Completion#

eval "$(bb completion)"          # bash or zsh
bb completion zsh >> ~/.zshrc

The emitted script supports both shells through bashcompinit. Pass bash or zsh as a hint; any other value exits 2.

Quick Examples#

bb query bank balances bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --output json   # chain native
bb api tokens get-collection 1                                                    # BitBadges API
bb build vault --backing-coin USDC --name "Demo Vault" \
  --image ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/vault.png \
  --description "USDC vault" \
  | bb preview - --open                                          # build, then review and sign in the browser
bb auth login --browser --address bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d   # session for Full Access routes
bb check tx.json && bb simulate tx.json                         # audit and dry-run

The first command, run against mainnet for an address that holds nothing, prints:

{
  "balances": [],
  "pagination": {}
}

Build a USDC vault called Demo Vault and give me a link to review and sign.

bb --help ends with the Chaosnet warning and a link to the policies at bitbadges.io/policies. Transactions use real tokens.

Related#

• Build
• Deploy
• Agents
• Quickstart