Installation
npm install -g @trunkbeam/cli
Or without installing, with npx @trunkbeam/cli <command>. Requires Node.js 22 or newer.
Sign in
In the dashboard, create an API key under API, CLI & MCP. Then:
trunkbeam login
The CLI asks for the key without echoing it, checks it and stores it in ~/.config/trunkbeam/config.json, readable only by your user. trunkbeam logout deletes it again.
On servers and in CI, set the environment variable instead:
export TRUNKBEAM_API_KEY=tb_live_…
Order of precedence: --key before TRUNKBEAM_API_KEY before the stored file.
Global options
| Option | Effect |
|---|---|
--json | Raw API data as JSON, for scripts |
--yes, -y | Run paid actions without asking |
--key <key> | Use a different API key for this call |
--help, -h | Help, also per command: trunkbeam numbers --help |
Commands
| Command | What it does |
|---|---|
login, logout | Sign the CLI in or out |
account | Account, verification status, plan and the key’s permissions |
sites | Sites with ID; only verified sites get local numbers |
onkz <place or area code> | Search an area code, for example onkz Schramberg |
numbers ls | Your numbers with ID, status and target |
numbers order --site <id> | Order a local number at the site, shows the price first |
numbers order --032 | Order an 032 number without an area code |
numbers connect <id> --elevenlabs | Connect a number to ElevenLabs in one step |
numbers connect <id> --sip-uri <uri> | Route a number to any SIP address |
numbers fallback <id> <number> | Fallback number if the agent is unreachable |
numbers release <id> | Cancel a number, asks first |
requests ls, requests rm <id> | View orders, withdraw open ones |
connections ls, connections add, connections rm <id> | Manage agent connections (SIP targets) |
guide <provider> --number <id> | Setup guide with your real values |
transfer get, transfer set, transfer reset | Transfer to people, as default or per number |
hold-music | Hold music with descriptions |
calls ls | Recent calls with duration, status and cost |
usage --month <YYYY-MM> | Usage and cost for a month |
prices | Plans and prices |
Providers for guide and connections add --provider: elevenlabs, livekit, livekit_self, vapi, retell, ultravox, openai, deepgram, sip.
In scripts
With --json and --yes, everything runs without prompts. Example: get a number at site 3 for a new customer and route it to their agent.
id=$(trunkbeam numbers order --site 3 --yes --json | jq -r '.assigned.id')
trunkbeam numbers connect "$id" --sip-uri "sip:customer-42@voice.example" --json
If no number is available right away, assigned is null and the order stays open. trunkbeam requests ls shows its status.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Error or cancelled |
2 | Invalid usage |