# Getting Started

The Fusion CLI (`bp-fusion`) lets you interact with the Bitpanda Fusion API directly from the terminal. You can query market data, manage orders, and inspect your account — no browser required.

## Prerequisites

Before installing the CLI, you need:

- A supported operating system: macOS, Linux, or Windows
- A Bitpanda Fusion API key

Create API key in your Bitpanda account under **Account settings → API Keys → Fusion** and assign the scopes required by your integration:

- **Read** for market data, balances, account information, and trade history
- **Trade** for placing and cancelling orders

See the [API key generation](https://docs.fusion.bitpanda.com/api-key-generation-363384m0.md) guide for step-by-step instructions.

---

## Installation

### Homebrew (macOS / Linux)

```bash
brew tap bitpanda-labs/tap
brew trust bitpanda-labs/tap
brew install bp-fusion
```

### Via Go

```bash
go install github.com/bitpanda-labs/bitpanda-fusion-cli/cmd/bp-fusion@latest
```

### From source

```bash
git clone https://github.com/bitpanda-labs/bitpanda-fusion-cli
cd bitpanda-fusion-cli
make install
```

`make install` builds the binary and copies it to `/usr/local/bin/bp-fusion`.

### Pre-built binaries

Download the latest binary for your platform from the [releases page](https://github.com/bitpanda-labs/bitpanda-fusion-cli/releases/latest).

Verify the installation:

```bash
bp-fusion --version
```

---

## Authentication

`bp-fusion` supports three ways to provide your API key, in priority order:

```bash
# 1. Flag (highest priority — useful for one-off commands)
bp-fusion account info --api-key YOUR_KEY

# 2. Environment variable
export FUSION_API_KEY=YOUR_KEY
bp-fusion account balances

# 3. Config file (~/.config/fusion/config.yaml)
```

### Config file setup (recommended)

```bash
mkdir -p ~/.config/fusion
cp config.example.yaml ~/.config/fusion/config.yaml
chmod 600 ~/.config/fusion/config.yaml   # restrict access — file contains your API key
```

Edit `~/.config/fusion/config.yaml`:

```yaml
api_key: YOUR_API_KEY_HERE
host: https://api.fusion.bitpanda.com  # optional, defaults to production
```

> **Tip:** `bp-fusion` will warn on stderr if the config file has permissions more permissive than `0600`.

---

## Your first command

Once authenticated, try fetching live ticker data for BTC-EUR:

```bash
bp-fusion tickers --pair BTC-EUR
```

For the full command reference — including market data, orders, trades, output formats, and shell completion — see the [Commands reference](https://docs.fusion.bitpanda.com/commands-370718m0.md).

---

## Global flags

| Flag | Env var | Description |
|---|---|---|
| `--api-key` | `FUSION_API_KEY` | API key (overrides config file) |
| `--host` | `FUSION_HOST` | Override the API host (default: production) |
| `--debug` | — | Print request URLs and raw responses to stderr |
| `-o`, `--output` | — | Output format: `table`, `json`, or `csv` |

---

## Output formats

All commands support `-o`/`--output`:

| Format | Flag | Description |
|---|---|---|
| Table | `-o table` (default) | Human-readable table |
| JSON | `-o json` | For scripting and piping |
| CSV | `-o csv` | For spreadsheets |

Examples:

```bash
bp-fusion tickers -o json | jq '.[] | select(.pair == "BTC-EUR")'
bp-fusion pairs -o csv > pairs.csv
bp-fusion trades list -o csv > trades.csv
```

## Shell completion

```bash
# Bash
source <(bp-fusion completion bash)

# Zsh
bp-fusion completion zsh > "${fpath[1]}/_bp-fusion"

# Fish
bp-fusion completion fish | source
```

---

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | General error |
| `2` | Authentication error |

---

## Troubleshooting

- **`401 Unauthorized` / exit code 2**: Check that your API key is set correctly and has not been revoked. Verify it at by following the [API key generation](https://docs.fusion.bitpanda.com/api-key-generation-363384m0.md).
- **`403 Forbidden` / insufficient scope**: The command requires a scope your key does not have. Enable the **Read** or **Trade** scope on your key.
- **`command not found: bp-fusion`**: Ensure the binary is on your `PATH`. Run `which bp-fusion` (macOS/Linux) or `where bp-fusion` (Windows) to confirm.
- **Unexpected API errors**: Run with `--debug` to print the full request and response: `bp-fusion --debug orders list`.
- **Config file permission warning**: Restrict access with `chmod 600 ~/.config/fusion/config.yaml`.

> **Need help?** If you encounter persistent issues, please reach out to Bitpanda Developer Support.