> For the complete documentation index, see [llms.txt](https://docs.bitbadges.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitbadges.io/for-developers/cli/installation.md).

# 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.

```bash
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

```bash
# 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-developers/ai-agents/claude-code-plugin.md) 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:

```bash
# npm
npm install -g bitbadges

# bun
bun install -g bitbadges
```

Verify:

```bash
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+):

```bash
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](https://github.com/BitBadges/bitbadgeschain/releases).

## Configuration

### API Key

Get an API key from the [BitBadges Developer Portal](https://bitbadges.io/developer), then configure it:

```bash
bb settings set apiKey YOUR_KEY
```

Or use environment variables:

```bash
export BITBADGES_API_KEY=YOUR_KEY
```

### Config File

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

```bash
# 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

```bash
# 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:

```bash
eval "$(bb completion)"
```

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