Installation

One-Liner (Recommended)

The fastest way to install everything. Detects your OS and architecture automatically, downloads the chain binary, and installs the SDK CLI.

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

This installs:

1. bitbadgeschaind — chain binary to /usr/local/bin/ (with the bb alias)

2. bitbadges-cli — SDK CLI via npm or bun (whichever is available). Reachable through the chain binary as bb <subcmd>.

Options

# Testnet binary
curl -fsSL https://install.bitbadges.io | sh -s -- --testnet

# Specific version
curl -fsSL https://install.bitbadges.io | sh -s -- --version v29

# Custom install directory
curl -fsSL https://install.bitbadges.io | sh -s -- --install-dir ~/.local/bin

# Skip sudo
curl -fsSL https://install.bitbadges.io | sh -s -- --no-sudo

Supported Platforms

Platform	Architecture	Status
Linux	x86_64 (amd64)	Supported
Linux	ARM64 (aarch64)	Supported
macOS	Intel (amd64)	Supported
macOS	Apple Silicon (arm64)	Supported
Windows	x86_64 (via Git Bash, MSYS2, WSL)	Supported

Optional add-on: Claude Code plugin

After the install above, Claude Code users can optionally install the BitBadges plugin for auto-wired MCP and 8 curated workflow skills:

/plugin marketplace add BitBadges/bitbadges-plugin
/plugin install bitbadges

The plugin is a convenience layer that builds on the CLI install above — it does not replace it.

SDK CLI Only (npm / bun)

If you only need the SDK CLI (API access, review tools, docs) without the chain binary:

# npm
npm install -g bitbadges

# bun
bun install -g bitbadges

Verify:

bb --help

The bb examples on every CLI page also work directly as bitbadges-cli <subcmd> when only the SDK CLI is installed.

Chain Binary Only (From Source)

If you only need the chain binary and want to build from source (requires Go 1.24+):

git clone https://github.com/BitBadges/bitbadgeschain.git
cd bitbadgeschain
make build-mainnet-linux/amd64   # or your platform

Pre-built binaries are also available on the GitHub Releases page.

Configuration

API Key

Get an API key from the BitBadges Developer Portal, then configure it:

bb settings set apiKey YOUR_KEY

Or use environment variables:

export BITBADGES_API_KEY=YOUR_KEY

Config File

The CLI reads ~/.bitbadges/config.json. Manage it with:

# Set values
bb settings set apiKey YOUR_KEY
bb settings set apiKeyTestnet YOUR_TESTNET_KEY
bb settings set network testnet
bb settings set url https://custom-api.example.com/api/v0

# View current config
bb settings show

# Remove a value
bb settings unset apiKeyTestnet

Supported keys: apiKey, apiKeyTestnet, apiKeyLocal, network (mainnet | testnet | local), url.

Environment Variables

Variable	Description
BITBADGES_API_KEY	Default API key (all networks)
BITBADGES_API_KEY_TESTNET	Testnet-specific API key
BITBADGES_API_KEY_LOCAL	Local-specific API key
BITBADGES_API_URL	Custom base URL (overrides config)

Network Flags

Flag	Description
--testnet	Use testnet API
--local	Use local API (http://localhost:3001)
--url <url>	Custom API base URL (overrides all others)

Resolution Order

API key: --api-key flag > network-specific env var > BITBADGES_API_KEY env var > network-specific config key > default config apiKey.

Base URL: --url flag > --local > --testnet > BITBADGES_API_URL env > config file > default production URL.

Verify Installation

# Check chain binary
bb version

# Check SDK CLI health
bb doctor

# Check API connectivity
bb doctor --testnet

Shell Completion

Generate bash/zsh completions for tab-completion:

eval "$(bb completion)"

Add that line to your .bashrc or .zshrc for persistent completions.