CLI Troubleshooting

Authentication

“no CLI identity configured”

You haven’t run init yet, or you’re pointing at a different config directory.

tokenbot init --label "this machine"
tokenbot whoami

If whoami works but another command doesn’t, check you aren’t passing a different --config (or have TOKENBOT_HOME set in your shell):

echo "$TOKENBOT_HOME"
tokenbot --config ~/.tokenbot whoami

Wrong passphrase

Your identity is encrypted at rest under the passphrase you chose during init. There is no recovery path — if it’s lost, register a new identity with tokenbot init and re-link it to your account.

Signature or timestamp rejected

Every request is signed and carries a timestamp; the server rejects stale ones. If requests fail after your machine has been asleep or your clock has drifted, sync it and retry.

The CLI does not authenticate with an API key. tokenbot apikey manages keys for your own integrations against the REST/GraphQL APIs — they are not used for the CLI’s own auth.

---

Installation

“command not found: tokenbot”

The npm global bin directory isn’t on your PATH:

npm list -g tokenbot
export PATH="$(npm config get prefix)/bin:$PATH"
tokenbot --version

Unsupported Node version

node --version   # must be v22.0.0 or newer

The CLI declares engines: { node: ">=22.0.0" }. A CLI installed under an older Node stays bound to it — switch versions first (nvm use 22), then reinstall.

---

Commands

“unknown command”

tokenbot --help              # every top-level command
tokenbot copier --help       # subcommands and flags for one command

The full set is: init, whoami, login, logout, keys, balance, link, unlink, links, strategy, copier, trades, exchange, webhooks, rewards, apikey.

“Invalid value for —side”

Enum flags accept any casing and are normalised, but the value has to be a real member. The error message lists what’s accepted. For tokenbot trades, --side takes buy or sell.

“missing required option”

Some commands take flags rather than positional arguments. link and unlink are the ones that catch people out — both require --copier and --strategy:

tokenbot link --copier cop_2d10 --strategy strat_9f

---

Output

A command prints nothing useful

Listing commands print an explanatory message when there are no rows rather than an empty table. That message is the answer — the command didn’t fail.

Parsing output in a script

Use --json. It always emits a well-formed array, [] included, so you never have to special-case the empty result:

tokenbot trades --limit 100 --json | jq '[.[].pnl | tonumber] | add'

--json also suppresses incidental human-facing text, so stdout stays valid JSON.

Truncated ids in tables

Tables shorten long ids for readability. --json always carries the full value.

---

Getting more help

tokenbot --help
tokenbot <command> --help

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