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


---

# 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/installation.md?ask=<question>
```

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.