Documentation

Quick Start

Get up and running in under a minute.

npm install -g wrelay

wrelay login -k YOUR_API_KEY

wrelay urls create my-project

wrelay listen my-project -p 3000

Authentication

The CLI authenticates with API keys created from the web dashboard.

Creating an API key

Go to Settings > API Keys in the dashboard. Give your key a name and select the permissions it needs. The key is shown once — copy it immediately.

API keys are prefixed with wrl_ and look like wrl_abc123def456....

Logging in

wrelay login -k wrl_YOUR_API_KEY

Credentials are stored locally:

• macOS: ~/Library/Preferences/wrelay-nodejs/
• Linux: ~/.config/wrelay/
• Windows: %APPDATA%\wrelay-nodejs\

Logging out

wrelay logout

Clears stored credentials. Your account and data remain on the server.

CLI Reference

All commands support --help for detailed usage info.

wrelay login -k <api-key>
wrelay login -k <api-key> -u http://localhost:4000  # self-hosted

wrelay logout

# List all URLs
wrelay urls list
wrelay urls list --json

# Create a new URL
wrelay urls create <path>
wrelay urls create staging --json

# Delete a URL
wrelay urls delete <path>

# List recent logs
wrelay logs list
wrelay logs list -u staging         # filter by URL
wrelay logs list -l 10              # limit results
wrelay logs list --json

# Show full details of a log
wrelay logs show <id>
wrelay logs show 123 --json

# Rename a log for easier identification
wrelay logs rename <id> <name>
wrelay logs rename 123 "stripe payment"

wrelay listen <url-path> -p <port>

# Examples
wrelay listen staging -p 3000                # forward to localhost:3000
wrelay listen api -p 8080 -H 0.0.0.0        # forward to 0.0.0.0:8080
wrelay listen api -p 3000 --path /webhooks   # forward to localhost:3000/webhooks
wrelay listen staging -p 3000 -v             # verbose output

wrelay replay <log-id>
wrelay replay 123 --json

Webhook URLs

Webhook URLs are permanent endpoints that receive HTTP requests and forward them to your CLI.

URL format

https://api.wrelay.app/@<handle>/<path>

For example, if your handle is alice and you create a path staging, your webhook URL is https://api.wrelay.app/@alice/staging.

Creating a URL

wrelay urls create staging

You can also create URLs from the web dashboard under URLs.

Configuring your webhook provider

Copy your full webhook URL and paste it into your provider's webhook settings:

• Stripe: Dashboard > Developers > Webhooks > Add endpoint
• GitHub: Repo Settings > Webhooks > Add webhook > Payload URL
• Any provider: Paste your wrelay URL wherever the service asks for a webhook/callback URL

All HTTP methods are accepted (GET, POST, PUT, PATCH, DELETE). Requests are logged immediately, even if no CLI is connected.

Listening & Forwarding

The wrelay listen command opens a real-time connection to receive webhooks and forward them to your local development server.

How it works

1. The CLI connects to the wrelay server via Server-Sent Events (SSE)
2. When a webhook arrives at your URL, the server pushes it to your CLI instantly
3. The CLI forwards the request to your local server, preserving method, headers, and body
4. Press Ctrl+C to disconnect

Output format

#1 POST [200] 45ms 10:30:45 AM
 |   |    |    |    └─ Local time
 |   |    |    └─ Response time from your server
 |   |    └─ HTTP status from your server
 |   └─ Original HTTP method
 └─ Request number in this session

Forwarding details

• Original HTTP method, headers, and body are preserved
• Hop-by-hop headers (Host, Connection, etc.) are filtered out
• Target URL: http://<host>:<port><path> (default: http://localhost:<port>/)

Reconnection

If the connection drops, the CLI reconnects automatically. Use -v to see heartbeat messages confirming the connection is alive.

Request Replay

Replay lets you resend a previously received webhook to all active listeners. Available on Solo and Team plans.

From the CLI

# Find the log you want to replay
wrelay logs list

# Start listening (in another terminal)
wrelay listen staging -p 3000

# Replay the webhook
wrelay replay 123

From the dashboard

Open Logs in the dashboard, click the actions menu on any log, and select Replay. You must have at least one active wrelay listen session for the replay to be delivered.

Use cases

• Debug your webhook handler without re-triggering the source
• Test error handling by replaying failed webhooks
• Share webhooks with teammates (they listen, you replay)

Request Logs

Every webhook received by your URLs is logged with full request details. Logs are stored based on your plan's retention period.

Viewing logs

# List recent logs
wrelay logs list

# Filter by URL
wrelay logs list -u staging

# View full request details
wrelay logs show 123

Log details include: HTTP method, path, all headers, query parameters, and body. JSON bodies are automatically formatted.

Naming logs

wrelay logs rename 123 "stripe checkout completed"

Names make it easier to find specific requests later. You can also name logs from the dashboard.

Scripting with JSON output

# Pipe to jq for advanced filtering
wrelay logs list --json | jq '.[].id'
wrelay logs show 123 --json | jq '.headers'

API Key Permissions

Each API key has a set of permissions that control what it can do. Select only the permissions you need when creating a key.

Recommended for development: select all permissions. For CI/CD or automated scripts, use the minimum set needed.

Plan Limits

Your plan determines resource limits and available features. You can upgrade at any time from the Billing page.