routely-tunnel

Routely development tunnel CLI. Exposes a local application to a webhook endpoint over a WebSocket: incoming webhooks are forwarded to localhost, and your local app's real response is returned to the original caller — like ngrok/Expose, but wired to your webhook endpoints.

Install

npm install -g routely-tunnel

Or run without installing (npx routely-tunnel …).

Usage

# 1. One-time: log in with your account token (generate it in the web panel)
routely-tunnel login <account-token>

# 2. Attach to one of your endpoints and forward to your local app
#    (no token needed — it's read from the saved login; port defaults to 3000)
routely-tunnel share --subdomain my-app

Forward to a local HTTPS site (e.g. a *.test site with a self-signed cert):

routely-tunnel share --subdomain my-app --target https://test.test

Self-signed certificates on local hosts (localhost, *.test, *.local) are trusted automatically — no --insecure needed. Use --insecure only to skip TLS verification for a non-local destination.

login saves the token to ~/.routely-tunnel/config.json, so you don't pass it again. logout removes it. config is still available for advanced use.

• The token is per account (one token for all your endpoints).
• --subdomain must match an endpoint you already created in the panel (e.g. my-app → https://my-app.<your-domain>).

start is kept as an alias of share.

Other commands

tail — watch live requests

Stream the requests an endpoint receives straight to your terminal, in real time, without needing a tunnel open:

routely-tunnel tail --subdomain my-app

Opens a full-screen live dashboard: a branded header with connection status and running stats (requests, ok, fail, p95 latency) above a table of the most recent requests — method, path, status and latency, colour-coded. It repaints on every event and on resize, and reconnects automatically.

It's interactive, like the web Inspector:

| Key | Action | | ------------------------ | ----------------------------------------------------------- | | ↑ / ↓ (or k / j) | Move the selection through the request list | | Enter | Open the selected request's detail view | | ← / → (or h / l) | Switch tabs — Request, Flow & delivery, Response, Tunnel | | ↑ / ↓ | Scroll the detail content | | b | Copy the body to the clipboard (pretty JSON when it's JSON) | | H | Copy the headers to the clipboard (Key: Value lines) | | Esc | Back to the list | | q / Ctrl-C | Quit |

b and H copy from whichever tab you're on — the Response tab yields the response body/headers, every other tab the captured request's.

The detail tabs are fetched on demand from the API (so headers, body, flow trace and forward results don't bloat the live stream). When output is piped (not a TTY), tail falls back to plain one-line-per-event logging.

replay — re-run a captured request

Replay a previously captured request through its endpoint's published flow. Copy the request id (req_…) from the panel:

routely-tunnel replay req_01KTDBRV3KX157GFE1FJ2GD8J2

The req_ prefix is optional. Replay runs the published flow, so the account must be entitled to flows (Pro plan or an active trial).

Options

| Option | Description | Default | | ----------------------- | ----------------------------------------------------------------------------------------- | -------------------------------- | | --subdomain <slug> | Endpoint subdomain to attach to — must already exist (required) | — | | -p, --port <port> | Local application port to forward to (or use --target) | 3000 | | --target <url> | Full destination URL (e.g. https://test.test); overrides host/port/scheme | — | | -H, --host <host> | Local application host | localhost | | -s, --scheme <scheme> | Local application scheme (http/https) | http | | -k, --insecure | Skip TLS verification for a non-local destination (local hosts are trusted automatically) | — | | -t, --token <token> | Account tunnel token | env/config | | --server <host\|url> | Tunnel server: a domain (e.g. tunnel.routely.me) or a full ws(s)://… URL | wss://tunnel.routely.me/tunnel | | --save | Persist the resolved server/token to the config file | — |

Configuration

Settings resolve in this order: flags → environment → saved config → defaults.

routely-tunnel config --token <account-token> --server tunnel.routely.me

By default the CLI connects to Routely's production tunnel server (wss://tunnel.routely.me/tunnel) — clients don't need to configure anything.

You can pass --server as just a domain (tunnel.routely.me → wss://tunnel.routely.me/tunnel) or as a full ws(s)://… URL. localhost/127.0.0.1 default to ws://; any other host defaults to wss://. The connected server is shown when the tunnel comes online.

Environment variables: ROUTELY_TUNNEL_TOKEN, ROUTELY_TUNNEL_SERVER, ROUTELY_API. Saved config lives at ~/.routely-tunnel/config.json.

The replay command talks to the HTTP API rather than the tunnel server. By default the API base is derived from --server (e.g. tunnel.routely.me → https://routely.me); override it with --api or ROUTELY_API if needed.

How it works

1. The CLI opens a WebSocket to the tunnel server and authenticates with your account token plus the subdomain you're attaching to.
2. When a webhook hits https://<subdomain>.<your-domain>, the server forwards the request frame to the CLI.
3. The CLI replays it against your local app and sends the response back.
4. The server returns that real response to the original caller.

Requires Node.js 18+.