> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tolt CLI

> @tolt/cli: stream your live webhooks to localhost and trigger sample events. No tunnel, no deploy.

`tolt listen` forwards your organization's webhooks to a local URL, re-signed so your handler verifies them like production.

tolt listen

\$ tolt listen -f http\://localhost:3000/api/tolt✓ Ready. Streaming all events to **http\://localhost:3000/api/tolt**  signing secret whsec\_Mz9kQ2xLpR7vT4nB8cWd3sYe  Ctrl+C to stop→ **customer.created** msg\_2nV8kQ4xRtLm9cWd 200→ **commission.created** msg\_7hTq2WmZr5LxVb3n 200

## Install

```bash theme={"system"}
npm install -g @tolt/cli
```

Or run any command without installing: `npx @tolt/cli listen`. Requires Node 18+.

## Test your webhook handler

**1. Log in**

Paste an API key from **Dashboard → Settings → Integrations → Tolt API**. The CLI checks it and stores it in `~/.config/tolt/config.json`. Pass `--api-url` too: the CLI still defaults to the older `api.tolt.com` host, and `login` saves the host only when it's passed this way.

```bash theme={"system"}
tolt --api-url https://platform.tolt.com login
```

**2. Start listening**

Point it at your local handler. It prints a signing secret: put it in `TOLT_WEBHOOK_SECRET` for your local server.

```bash theme={"system"}
tolt listen --forward-to http://localhost:3000/api/webhooks/tolt
```

**3. Trigger an event**

In a second terminal, send a sample event to the running `listen` session.

```bash theme={"system"}
tolt trigger commission.created
```

The `listen` terminal shows the event and the status your handler returned.

Forwarded requests carry the usual `svix-id`, `svix-timestamp` and `svix-signature` headers, so the same [`verifyWebhook()`](/sdks/webhooks) code works locally and in production. Without `--forward-to`, `listen` just prints each event.

## Commands

| Command | |
| - | - |
| `tolt login` | Verify an API key and save it to the active profile. |
| `tolt whoami` | Show the active profile and check the key still works. |
| `tolt logout` | Remove the stored key for a profile. |
| `tolt listen` | Stream your webhooks. `-f, --forward-to <url>` to POST them to a local URL, `-e, --events <list>` to filter (e.g. `commission.created,customer.created`). |
| `tolt trigger <event>` | Send a sample event through the running `listen` session. Any [event type](/webhooks/event-types). |

## Global flags

| Flag | |
| - | - |
| `--token <key>` | API key for this command only. |
| `--profile <name>` | Use a named profile, to switch between accounts. |
| `--api-url <url>` | Point at a different API host. |
| `--json` / `--human` | Force JSON or human output. |
| `-v, --version` | Print the version. |

The API key resolves in this order: `--token`, then `TOLT_API_KEY`, then the active profile. The host comes from `--api-url`, then `TOLT_API_URL`, then the active profile (saved by `tolt --api-url … login`).

## Scripting

Output is human-readable on a terminal and JSON when piped (or with `--json`, or `TOLT_JSON=true`). In JSON mode, errors are `{"error": "message"}` on stdout with exit code `1`.

```bash theme={"system"}
tolt listen --json \
  | jq -r 'select(.forwarded) | "\(.forwarded) \(.status)"'
```

> [!NOTE]
>
> `tolt listen` only forwards while it runs. Your production endpoints keep receiving events as configured in the dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.