> For the complete documentation index, see [llms.txt](https://docs.tokenbot.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tokenbot.com/home/05-cli-reference.md).

# The TokenBot CLI

**Everything in TokenBot runs through the `tokenbot` command. This is the complete command reference.**

> 📢 **Official Announcements**: Follow [@TokenBotV2 on X](https://x.com/tokenbot) for news and updates.

***

## Install

```bash
# npm (public registry)
npm install -g tokenbot

# or Homebrew
brew tap tokenbot-org/tokenbot
brew install tokenbot
```

Requires **Node.js 22 or newer**. Check your install with `tokenbot --version`.

### Global options

| Flag              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `--json`          | Emit machine-readable JSON instead of tables (great for scripting) |
| `--config <path>` | Use an alternate config directory instead of `~/.tokenbot`         |
| `--version`       | Print the CLI version                                              |
| `--help`          | Show help for any command                                          |

***

## Identity

Your identity is a secp256k1 keypair created on first run and stored encrypted at `~/.tokenbot/config.json`.

| Command           | What it does                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `tokenbot init`   | Generate a CLI identity and register it with TokenBot. Flags: `--label`, `--api-url`, `--ws-url` |
| `tokenbot whoami` | Print your active identity and the server-side account it maps to                                |
| `tokenbot login`  | Confirm your identity is configured (run `init` if it isn't)                                     |
| `tokenbot logout` | Delete your local config and encrypted key store (double-confirmed)                              |

***

## Local Exchange Keys

These credentials are encrypted **on your machine** and are never sent to the server. They power local commands like `balance`.

| Command                        | What it does                                                                                                                     |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `tokenbot keys add`            | Add or replace an exchange credential for a strategy or copier. Flags: `--strategy <id>` or `--copier <id>`, `--exchange <name>` |
| `tokenbot keys list`           | List the labels of stored credentials                                                                                            |
| `tokenbot keys remove <label>` | Delete the credential under `<label>` (double-confirmed)                                                                         |

***

## Balances

| Command            | What it does                                                                                    |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `tokenbot balance` | Fetch exchange balances locally via CCXT. One of `--strategy <id>`, `--copier <id>`, or `--all` |

***

## Exchange Accounts (server-side)

Registering an account sends its credentials to TokenBot so the automated engines can trade. Use this only when you want server-side automation.

| Command                       | What it does                                                                             |
| ----------------------------- | ---------------------------------------------------------------------------------------- |
| `tokenbot exchange list`      | List your registered exchange accounts                                                   |
| `tokenbot exchange add`       | Register a new exchange account. Flags: `--exchange`, `--account-name`, `--trading-type` |
| `tokenbot exchange supported` | List exchanges the server can connect to                                                 |

***

## Strategies

A Strategy is the account whose trades get replicated.

| Command                         | What it does                                                                             |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| `tokenbot strategy list`        | List the strategies you own                                                              |
| `tokenbot strategy show <id>`   | Show a single strategy (JSON)                                                            |
| `tokenbot strategy add`         | Create a strategy. Flags: `--name`, `--description`, `--exchange-account-id`, `--public` |
| `tokenbot strategy delete <id>` | Delete a strategy (double-confirmed)                                                     |

***

## Copiers

A Copier follows a Strategy and replicates its trades onto another account.

| Command                       | What it does                                                                                                                                                            |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenbot copier list`        | List the copiers you own                                                                                                                                                |
| `tokenbot copier show <id>`   | Show a single copier (JSON)                                                                                                                                             |
| `tokenbot copier add`         | Create a copier. Flags: `--strategy`, `--exchange-account-id`, `--name`, `--allocation` (0–100). Created **inactive** — it copies nothing until you run `tokenbot link` |
| `tokenbot copier delete <id>` | Delete a copier (double-confirmed)                                                                                                                                      |

***

## Linking

| Command               | What it does                                                               |
| --------------------- | -------------------------------------------------------------------------- |
| `tokenbot link`       | Bind a copier to a strategy. Flags: `--strategy <id>`, `--copier <id>`     |
| `tokenbot unlink`     | Detach a copier from a strategy. Flags: `--strategy <id>`, `--copier <id>` |
| `tokenbot links list` | List every copier alongside the strategy it follows                        |

***

## Webhooks

Register HTTPS endpoints to receive real-time event notifications.

| Command                         | What it does                                                            |
| ------------------------------- | ----------------------------------------------------------------------- |
| `tokenbot webhooks list`        | List your webhook endpoints                                             |
| `tokenbot webhooks add`         | Register an endpoint. Flags: `--url`, `--events <csv>`, `--description` |
| `tokenbot webhooks remove <id>` | Delete an endpoint (double-confirmed)                                   |
| `tokenbot webhooks test <id>`   | Send a test event to an endpoint                                        |

See the [API documentation](https://github.com/tokenbot-org) for the full list of webhook event types and signature verification.

***

## Rewards & Referrals

| Command                  | What it does              |
| ------------------------ | ------------------------- |
| `tokenbot rewards show`  | Show your rewards summary |
| `tokenbot rewards refer` | Print your referral code  |

***

## API Keys (for the REST/GraphQL APIs)

These are **server-side** keys for programmatic access to the TokenBot API — distinct from the local exchange keys managed by `tokenbot keys`.

| Command                       | What it does                                                                                                             |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `tokenbot apikey list`        | List your active API keys (secrets hidden)                                                                               |
| `tokenbot apikey create`      | Create a key (the secret is printed once). Flags: `--name`, `--description`, `--env <live\|test>`, `--permissions <csv>` |
| `tokenbot apikey revoke <id>` | Revoke a key (double-confirmed)                                                                                          |

***

## A Typical First Session

```bash
npm install -g tokenbot
tokenbot init                                   # create your identity
tokenbot keys add --strategy <id>               # store keys locally, or:
tokenbot exchange add                           # register an account for the bots
tokenbot strategy add --name "Main"             # create a strategy
tokenbot copier add --strategy <id> --allocation 50
tokenbot link --strategy <id> --copier <id>     # wire them together
tokenbot links list                             # confirm
```

***

## Next Steps

* [Bot Operator CLIs →](https://github.com/tokenbot-org/tokenbot-docs/tree/main/home/11-bot-operator-clis/README.md) — the advanced `tokenbot-mm` / `tokenbot-trading` operator CLIs
* [Rewards & Referrals →](https://github.com/tokenbot-org/tokenbot-docs/tree/main/home/06-rewards-and-referrals/README.md)
* [Security & Trust →](https://github.com/tokenbot-org/tokenbot-docs/tree/main/home/08-security-and-trust/README.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.tokenbot.com/home/05-cli-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.