Command-line interface

Relayers CLI

relayers is the terminal companion to the desktop app. It opens a webhook tunnel from any provider — Stripe, GitHub, anything — straight to your localhost, and lets you manage every part of your account: endpoints, routing rules, transformations, events, daemons and API tokens.

Install

On macOS or Linux, one line installs the latest relayers (amd64 or arm64, auto-detected) and verifies its checksum:

macOS · Linux

curl -fsSL https://dl.relayers.app/cli/install.sh | sh

It installs to /usr/local/bin when writable, otherwise ~/.local/bin. Override with RELAYERS_INSTALL_DIR. Prefer to read before piping to a shell? Read install.sh first.

Or download a binary

macOS

Linux

Windows

x86-64 (amd64)

Extract and put relayers on your PATH. On Windows, unzip and add relayers.exe. Checksums: checksums.txt.

Quickstart

1 · authenticate

relayers login

2 · start the tunnel

relayers listen --port 3000

Webhooks delivered to your Relayers endpoint now arrive at http://localhost:3000. The tunnel reconnects automatically and stays alive while idle — the same URL keeps working across restarts. Restrict a session to specific endpoints with --endpoints <slug-or-id>,….

Authentication

relayers login stores your session in the OS keychain (with an encrypted-file fallback). Check it anytime:

session status

relayers status

Non-interactive auth (CI / scripts)

Set RELAYERS_TOKEN (a JWT or a wrk_ API key) to authenticate without logging in — it bypasses the stored session entirely. Point at a different environment with RELAYERS_SERVER.

stateless auth

export RELAYERS_TOKEN="wrk_…"                       # from: relayers tokens create
export RELAYERS_SERVER="https://api.relayers.app"   # optional
relayers endpoints list

Log out and clear the stored session with relayers logout.

Endpoints

Endpoints are the URLs providers send webhooks to. Create one, and its public_id becomes your receive URL: https://api.relayers.app/v1/webhooks/<public_id>.

manage endpoints

relayers endpoints list
relayers endpoints list --json           # machine-readable (any command)

# create (a slug is generated from the name if you omit --slug)
relayers endpoints create --name "Stripe prod" --rate-limit 100

relayers endpoints get <endpointID>
relayers endpoints update <endpointID> --rate-limit 50 --active=false
relayers endpoints delete <endpointID>

Routing rules

Rules decide where each event goes. A rule delivers to a public URL or down a tunnel, in priority order (lower runs first), and can apply a transformation.

manage rules (nested under an endpoint)

relayers endpoints rules list <endpointID>

# deliver to your tunnel
relayers endpoints rules create <endpointID> \
  --name to-localhost --destination-type tunnel --priority 1

# deliver to a public URL, applying a transformation
relayers endpoints rules create <endpointID> \
  --name forward --destination-type public \
  --destination-url https://example.com/hook \
  --transform-id <transformID> --priority 2

relayers endpoints rules update <endpointID> <ruleID> --status paused
relayers endpoints rules reorder <endpointID> <ruleID2> <ruleID1>
relayers endpoints rules delete <endpointID> <ruleID>

Filter which events a rule matches with --filter (a JQ/JSON object), e.g. --filter '{"type":"payment.succeeded"}'.

Events & deliveries

Every received webhook is an event; each rule it matches produces delivery attempts. Inspect and replay them:

events

relayers events list --limit 20
relayers events get <eventID>
relayers events deliveries <eventID>     # per-rule attempts + response codes
relayers events retry <eventID>          # re-run delivery

relayers logs                            # alias for a recent events feed

Transformations

Reshape payloads before delivery. Types: jq, jsonata, javascript, go_template. Test an expression against sample input before saving it:

transformations

relayers transformations test \
  --type jq --expression '{ id: .id, amount: .data.amount }' \
  --input '{"id":"evt_1","data":{"amount":4200}}'

relayers transformations create \
  --name flatten --type jq --expression '{ id: .id, amount: .data.amount }'

relayers transformations list
relayers transformations get <transformID>
relayers transformations update <transformID> --expression '.data'
relayers transformations delete <transformID>

API tokens

API keys (wrk_-prefixed) authenticate scripts and the tunnel. The raw token is shown once at creation — copy it then.

tokens

relayers tokens create --name ci --scope read --scope write
# ⚠  Save this token now — it will not be shown again:
#     wrk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

relayers tokens list
relayers tokens revoke <tokenID>

Daemons (remote tunnels)

Each running relayers listen registers a daemon. Manage them across machines:

daemons

relayers daemons list                    # status, host, OS, last-seen
relayers daemons get <daemonID>
relayers daemons rename <daemonID> "laptop"
relayers daemons ping <daemonID>         # requires the daemon to be online
relayers daemons delete <daemonID>

Stats, billing & account

account

relayers stats                           # 24h event totals + success rate
relayers billing usage
relayers billing subscription
relayers billing plans
relayers billing portal                  # opens the billing portal URL

relayers account export                  # GDPR/LGPD data export (JSON)
relayers account delete --yes            # irreversible — requires --yes

Run as a background service

Keep the tunnel up without a terminal open. install copies the binary to a stable location, saves the config, and registers a per-user service that starts automatically on login (no root required). Its flags mirror listen: --port, --host, --name, --endpoints.

background service

relayers install --port 3000     # install + auto-start on login
relayers service status
relayers service stop
relayers service start
relayers service restart

relayers uninstall               # remove the service
relayers uninstall --purge       # also remove the binary, config and logs

Check the CLI build with relayers version, and generate shell completions with relayers completion <bash|zsh|fish>.

Global conventions

--json — every read command can emit JSON for piping into jq or scripts.
--server <url> / RELAYERS_SERVER — target a specific environment.
relayers <command> --help — full flags for any command.

Prefer a UI?

The desktop app does everything the CLI does — a live payload inspector, local forwarding rules, and a tray icon — on macOS, Windows, and Linux.

Download Relayers Desktop