# CLI

Installation, login and every command of the command line tool.

> Early access: these interfaces are documented as drafts. Confirm commands, packages and endpoints with us before use.

Source: https://trunkbeam.com/en/docs/cli

## Installation

```bash
npm install -g @trunkbeam/cli
```

Or run it without installing via `npx @trunkbeam/cli`. Requires Node.js 20 or newer.

## Log in

```bash
trunkbeam login
```

`login` opens the browser to confirm. On servers without a browser, set the environment variable instead:

```bash
export TRUNKBEAM_API_KEY=tb_live_…
```

Keep several accounts apart with profiles, for example `trunkbeam login --profile client-a` and then `--profile client-a` on every command.

## Global options

| Option | Effect |
| --- | --- |
| `--json` | JSON output for scripts |
| `--yes` | Skip confirmations, for example when buying |
| `--profile <name>` | Use another account |
| `--help` | Help for any command |

## Commands

| Command | What it does |
| --- | --- |
| `signup` | Create an account |
| `login`, `logout` | Log the CLI in or out |
| `status` | Verification status of your account |
| `verify --docs <file>` | Submit documents |
| `addresses list`, `addresses add` | Addresses for more area codes |
| `numbers search --area <code>` | Search available numbers |
| `numbers buy <number> --sip <uri>` | Buy a number and connect it |
| `numbers list` | Your numbers with status |
| `numbers update <number> --sip <uri>` | Change the target |
| `numbers release <number>` | Cancel a number at month end |
| `transfer allow <number> --to <targets>` | Allowed targets for SIP REFER |
| `trunks create --name <name>` | Credentials for outbound calls |
| `calls list` | Recent calls with duration and cost |
| `prices` | Current price list |
| `usage --month <YYYY-MM>` | Usage and cost for a month |
| `keys create`, `keys list`, `keys revoke` | Manage API keys |

## In scripts

With `--json` and `--yes` nothing asks for confirmation. Example: get a number in the right area code for every new customer.

```bash
number=$(trunkbeam numbers search --area 089 --json | jq -r '.[0].number')
trunkbeam numbers buy "$number" --sip "sip:customer-42@voice.example" --yes --json
```

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | General error |
| `2` | Invalid input |
| `3` | Not logged in or invalid key |
| `4` | Account not approved yet |
| `5` | Spend limit reached |