> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Trade, manage accounts, and query market data from the terminal using the WhiteBIT CLI. Built for scripting, CI/CD pipelines, and automated workflows.

The WhiteBIT CLI provides 110+ commands covering the full WhiteBIT API surface — market data, spot trading, collateral trading, lending, sub-accounts, deposits, and withdrawals — directly from the terminal.

## Prerequisites

* A WhiteBIT account with an API key for authenticated commands — see [Authentication](/api-reference/authentication)

Public market data commands (`market`, `server`) require no account or API key.

| Feature              | Detail                                                                           |
| -------------------- | -------------------------------------------------------------------------------- |
| **110+ commands**    | Full API surface: spot, collateral, lending, sub-accounts, deposits, withdrawals |
| **Multi-profile**    | Named profiles in `~/.whitebit/config.toml`, switch with `--profile`             |
| **`--dry-run` mode** | Preview the exact request payload before sending                                 |
| **JSON output**      | `--json` flag on every command — pipe into `jq` or any automation tool           |
| **Shell completion** | Tab-completion for Bash, Zsh, and Fish                                           |
| **Cross-platform**   | macOS (ARM + x64), Linux, and Windows                                            |

## Install the CLI

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    brew install whitebit-exchange/tap/whitebit
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install -g whitebit-cli
    ```
  </Tab>

  <Tab title="From source">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    git clone https://github.com/whitebit-exchange/whitebit-cli
    cd whitebit-cli
    bun install
    bun src/cli.ts --help
    ```

    Requires [Bun](https://bun.sh) ≥ 1.0.0.
  </Tab>
</Tabs>

## Quick start

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Set credentials (required for account and trading commands)
export WHITEBIT_API_KEY="YOUR_API_KEY"
export WHITEBIT_API_SECRET="YOUR_SECRET"

# 2. Verify setup — no authentication required
whitebit market info

# 3. Check the spot balance
whitebit spot balance

# 4. Place a limit order
whitebit spot limit-order --market BTC_USDT --side buy --amount 0.001 --price 50000
```

## Authentication

Credentials are resolved in priority order (highest first):

| Method                                  | Best for                       | Persistence | Security note               |
| --------------------------------------- | ------------------------------ | ----------- | --------------------------- |
| CLI flags (`--api-key`, `--api-secret`) | Quick testing                  | None        | Visible in process list     |
| Environment variables                   | CI/CD, Docker, one-off scripts | Per-session | Depends on environment      |
| Config file (`~/.whitebit/config.toml`) | Daily use, multiple profiles   | Permanent   | Set `chmod 600` on the file |

<Warning>
  Store API keys securely. Do not commit `~/.whitebit/config.toml` to version control. Avoid `--api-key` flags in production scripts — the value is visible in the process list.
</Warning>

### Config file

Create `~/.whitebit/config.toml` with one or more named profiles:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[default]
api_key = "YOUR_API_KEY"
api_secret = "YOUR_SECRET"
default_format = "table"  # or "json"

[work]
api_key = "WORK_API_KEY"
api_secret = "WORK_SECRET"
```

Switch profiles with `--profile`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
whitebit spot balance --profile work
```

## Commands

| Module        | Commands | Auth | Description                                                      |
| ------------- | -------- | :--: | ---------------------------------------------------------------- |
| `server`      | 3        |  No  | Server ping, time, and maintenance status                        |
| `market`      | 11       |  No  | Markets, order book, trades, depth, funding rates, assets        |
| `spot`        | 14       |  Yes | Limit, market, stop orders; cancel, modify, kill-switch          |
| `collateral`  | 16       |  Yes | Margin: leverage, positions, OCO, conditional orders             |
| `account`     | 7        |  Yes | Main balance, history, deposit address, withdraw, transfer, fees |
| `convert`     | 3        |  Yes | Estimate and execute asset conversions                           |
| `lending`     | 11       |  Yes | Fixed and flexible staking, interest history                     |
| `mining`      | 6        |  Yes | Rewards, hashrate, worker stats, payout destination              |
| `sub-account` | 10       |  Yes | Sub-account management, balances, transfers                      |
| `config`      | 2        |  No  | Manage CLI credentials and profiles                              |

## Examples

### Market data

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# List all available markets
whitebit market info

# Get 24h pricing and volume for all markets
whitebit market activity

# Get order book
whitebit market orderbook --market BTC_USDT

# Get recent trades
whitebit market trades --market BTC_USDT
```

### Account and balance

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Check spot balance
whitebit spot balance

# Check main account balance
whitebit account main-balance

# Transfer 100 USDT from main to spot
whitebit account transfer --from main --to spot --ticker USDT --amount 100
```

### Spot trading

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Place a limit buy order
whitebit spot limit-order --market BTC_USDT --side buy --amount 0.001 --price 50000

# Place a market sell order
whitebit spot market-order --market BTC_USDT --side sell --amount 0.001

# List open orders
whitebit spot active-orders --market BTC_USDT

# Cancel an order
whitebit spot cancel --market BTC_USDT --order-id ORDER_ID
```

### JSON output and scripting

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Output as JSON
whitebit spot balance --json

# Pipe into jq
whitebit spot balance --json | jq '.[] | {currency: .currency, balance: .available}'

# Dry run — preview the request without sending
whitebit spot limit-order --market BTC_USDT --side buy --amount 0.001 --price 50000 --dry-run
```

## Shell completion

<Tabs>
  <Tab title="Bash">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    whitebit completion --shell bash >> ~/.bash_completion
    ```

    To load automatically, add `source ~/.bash_completion` to `~/.bashrc`.
  </Tab>

  <Tab title="Zsh">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    mkdir -p ~/.zfunc
    whitebit completion --shell zsh > ~/.zfunc/_whitebit
    ```

    Add `fpath=(~/.zfunc $fpath)` and `autoload -Uz compinit && compinit` to `~/.zshrc`.
  </Tab>

  <Tab title="Fish">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    whitebit completion --shell fish > ~/.config/fish/completions/whitebit.fish
    ```
  </Tab>
</Tabs>

## Global options

| Option                   | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `--profile <name>`       | Use a named config profile (default: `default`) |
| `--api-key <key>`        | Override the API key for this command           |
| `--api-secret <secret>`  | Override the API secret for this command        |
| `--api-url <url>`        | Override the API base URL                       |
| `--format <table\|json>` | Output format                                   |
| `--json`                 | Shorthand for `--format json`                   |
| `--verbose`, `-V`        | Show raw API responses                          |
| `--dry-run`              | Show the request payload without sending        |

## Exit codes

| Code | Meaning                            |
| ---- | ---------------------------------- |
| `0`  | Success                            |
| `1`  | General error                      |
| `2`  | Authentication or credential error |
| `3`  | Network error                      |
| `4`  | Usage or bad arguments             |
| `5`  | Rate limit (HTTP 429)              |

## Security best practices

* Never commit credentials to version control.
* Use environment variables for CI/CD pipelines.
* Set restrictive file permissions: `chmod 600 ~/.whitebit/config.toml`.
* Use API key restrictions in the WhiteBIT dashboard — IP whitelist and read-only scope when appropriate.
* Avoid `--api-key` and `--api-secret` flags in production scripts — values are visible in the process list.

## What's next

* [MCP server](/guides/mcp-server) — Use natural language to trade and query data via an AI client
* [AI tools FAQ](/guides/ai-faq) — Common questions about the CLI, API keys, and automation
* [AI tools overview](/guides/use-with-ai) — All WhiteBIT AI tools in one place
* [Authentication](/api-reference/authentication) — How to generate and manage WhiteBIT API keys
* [API Reference Overview](/api-reference/overview) — Full REST API endpoint listing