CLI Examples & Use Cases

Worked examples using real tokenbot commands. Every command here exists in the shipped CLI — run tokenbot --help to see the same list.

Two global flags apply to everything below:

Flag	Effect
`--json`	Emit JSON instead of a table, for piping into `jq` and friends
`--config <path>`	Use a different config directory (sets `TOKENBOT_HOME`)

Sample output below is illustrative — ids, symbols and figures are made up. Column headings match what the CLI actually prints, and ids appear truncated because the CLI shortens them for display (--json always gives you the full value).

Use Case 1: First run — register a CLI identity

tokenbot init --label "work laptop"

init generates a secp256k1 keypair, encrypts it under a passphrase you choose, and registers the public key with TokenBot. Everything else needs this first.

Check it worked:

tokenbot whoami

Use Case 2: See what you’ve traded

tokenbot trades

┌──────────────────────┬──────────┬──────┬────────┬────────┬──────────┬────────┬───────────┬───────────┐
│ executed (utc)       │ symbol   │ side │ status │ qty    │ price    │ pnl    │ strategy  │ id        │
├──────────────────────┼──────────┼──────┼────────┼────────┼──────────┼────────┼───────────┼───────────┤
│ 2026-08-15 14:02:11  │ BTC/USDT │ buy  │ filled │ 0.0120 │ 61240.50 │ +18.40 │ strat_9f… │ trd_4a1c… │
│ 2026-08-15 09:41:03  │ ETH/USDT │ sell │ filled │ 0.4500 │  3180.20 │ −6.05  │ strat_9f… │ trd_39b8… │
└──────────────────────┴──────────┴──────┴────────┴────────┴──────────┴────────┴───────────┴───────────┘

With no trades yet you get an explanation rather than an empty table — the command tells you your account is empty, not that it failed.

Narrow it down:

tokenbot trades --symbol BTC/USDT --side buy --since 2026-08-01 --limit 20

Filters available: --strategy, --symbol, --side, --since, --until, --limit, --page. When a full page comes back, the CLI prints a footer telling you to use --limit or --page for more.

Use Case 3: Pipe into `jq` for scripting

Every listing command takes --json, which always emits an array — [] when empty — so scripts can parse unconditionally without special-casing the no-rows path.

# Total PnL across your last 100 trades
tokenbot trades --limit 100 --json | jq '[.[].pnl | tonumber] | add'

# Just the ids of active strategies
tokenbot strategy list --json | jq -r '.[] | select(.active) | .id'

Use Case 4: Set up copy trading end to end

Copy trading binds a copier (the follower) to a strategy (the leader).

# 1. Register the exchange account the copier will trade on
tokenbot exchange add --exchange binance --account-name "main" --trading-type spot

# 2. See which strategies are available to follow
tokenbot strategy list

# 3. Create a copier against one of them, allocating 25% of the account
tokenbot copier add --strategy strat_9f --exchange-account-id exa_71 --name "btc follow" --allocation 25

# 4. Confirm the binding
tokenbot links list

┌──────────┬──────────┬────────────┬────────┬────────┐
│ copier   │ strategy │ name       │ status │ active │
├──────────┼──────────┼────────────┼────────┼────────┤
│ cop_2d10 │ strat_9f │ btc follow │ active │ true   │
└──────────┴──────────┴────────────┴────────┴────────┘

To rebind or detach later:

# Both take flags — neither accepts positional ids
tokenbot link --copier cop_2d10 --strategy strat_4e7
tokenbot unlink --copier cop_2d10 --strategy strat_9f

unlink still wants --strategy even though the copier id is the lookup key — it is required for clarity, so you can see which binding you are removing.

Use Case 5: Two accounts side by side

--config swaps the whole config directory, so separate identities never share a key store.

tokenbot --config ~/.tokenbot-personal strategy list
tokenbot --config ~/.tokenbot-work strategy list

TOKENBOT_HOME does the same thing via the environment:

export TOKENBOT_HOME=~/.tokenbot-work
tokenbot whoami

Use Case 6: Check balances without sending keys anywhere

tokenbot keys add --exchange binance --strategy strat_9f
tokenbot balance --strategy strat_9f

Credentials added with keys add are stored encrypted in ~/.tokenbot/keys.json and never transmitted. balance uses them locally, calling the exchange directly through ccxt.

# Every stored credential at once
tokenbot balance --all

This is distinct from tokenbot exchange add, which deliberately does register credentials server-side so the platform can trade on your behalf. Two separate paths — see Exchange Accounts.

Use Case 7: A health check you can cron

#!/usr/bin/env bash
set -euo pipefail

if ! tokenbot whoami --json > /dev/null 2>&1; then
  echo "tokenbot identity not configured or unreachable" >&2
  exit 1
fi

inactive=$(tokenbot copier list --json | jq '[.[] | select(.active | not)] | length')
if [ "$inactive" -gt 0 ]; then
  echo "warning: $inactive copier(s) inactive" >&2
fi

Use Case 8: Webhooks for your own tooling

tokenbot webhooks add --url https://example.com/hooks/tokenbot --events trade.filled,copier.changed
tokenbot webhooks list
tokenbot webhooks test wh_5c

webhooks test sends a test event so you can confirm your endpoint before relying on it.

Use Case 9: API keys for programmatic access

tokenbot apikey create --name "ci-reporting" --env test

The secret is printed exactly once and never again — capture it at creation time. --env accepts live or test and defaults to live. --permissions takes a comma-separated list; run tokenbot apikey create --help for the values your account accepts.

tokenbot apikey list
tokenbot apikey revoke key_88

Use Case 10: Rewards and referrals

tokenbot rewards show
tokenbot rewards refer

Full command list

init · whoami · login · logout · keys · balance · link · unlink · links · strategy · copier · trades · exchange · webhooks · rewards · apikey

See the Command Reference for every subcommand and flag.