Getting Started with the TokenBot CLI

TokenBot is CLI-first. tokenbot is the command-line tool you use to manage strategies, copiers, exchange accounts, balances, trades, webhooks and rewards.

There is one user CLI. @tokenbot-org/cli-core, @tokenbot-org/sdk and @tokenbot-org/data-models are libraries on GitHub Packages, not things you install to use TokenBot.

---

5-minute quickstart

1. Install

Requires Node.js 22+.

npm install -g tokenbot

2. Register a CLI identity

tokenbot init --label "work laptop"

This generates a secp256k1 keypair, encrypts it under a passphrase you choose, and registers the public key with TokenBot.

You are not asked for an API key. The CLI authenticates by signing each request with your private key — the key never leaves your machine, and there is no shared secret to paste or leak. API keys (tokenbot apikey) exist for your own programmatic integrations, not for the CLI’s own auth.

3. Confirm it worked

tokenbot whoami

Prints the active identity and the account it maps to server-side.

4. Run your first real command

tokenbot strategy list

Empty on a new account — that’s expected. Read-only listing commands say so in words rather than printing a bare empty table.

---

Output formats

Every command supports one global flag for machine-readable output:

tokenbot trades            # human-readable table (default)
tokenbot trades --json     # JSON, for piping to jq

--json always emits a well-formed array — [] when there are no rows — so scripts never need to special-case the empty result.

---

Global flags

Flag	Effect
--json	Output JSON instead of a table
--config <path>	Use a different config directory (also settable via TOKENBOT_HOME)
--version	Print the CLI version
--help	Help for any command or subcommand

Use --config to keep separate identities side by side:

tokenbot --config ~/.tokenbot-work whoami

---

Where your data lives

Path	Contents
~/.tokenbot/config.json	your CLI identity, encrypted under your passphrase
~/.tokenbot/keys.json	local-only exchange credentials, encrypted, never transmitted

tokenbot logout deletes both.

Note the deliberate split: tokenbot keys add stores credentials locally for commands like tokenbot balance, which call the exchange directly. tokenbot exchange add is a separate path that registers credentials server-side so the platform can act for you. See Exchange Accounts.

---

Next steps

• Installation Guide — requirements, PATH problems, project-local installs
• Command Reference — every command and flag
• Examples — worked end-to-end use cases
• Troubleshooting — common errors

Getting help

tokenbot --help            # all commands
tokenbot copier --help     # one command and its subcommands

Issues: github.com/tokenbot-org/data-models/issues — the CLI ships from the data-models workspace.