Skip to main content
Local forwarding is the CLI workflow for receiving real webhook traffic on your machine.
A provider sends an event to a bucket. An internal forwarder waits for the CLI, and the CLI sends the request to localhost.

​
What you need

A bucket

The bucket receives webhook traffic from a provider.

An internal forwarder

repost forward listens only to internal forwarders.

A local endpoint

Your app must be running at the target URL configured on the forwarder.

​
Start a session

repost forward resolves a bucket first, then resolves internal forwarders inside that bucket.
Run without flags to choose the bucket and forwarders from prompts.
repost forward
If you provide --bucket-slug or --forwarder, provide both. Partial flag usage is rejected so the CLI never connects to an ambiguous target.
--bucket-slug expects a bucket slug. --forwarder expects an internal forwarder name. External forwarders are filtered out because they are delivered by Repost.

​
Pending events

When a forwarder has events waiting, the CLI can ask what to do, process pending events first, or skip straight to new traffic.
Default behavior. The TUI asks how to handle pending events before it starts real-time delivery.
repost forward -b stripe-prod -f local-webhooks
Avoid combining --pending-first and --skip-pending. If both flags are present, --skip-pending takes precedence.
If pending events appear after reconnecting, the TUI asks per forwarder whether to receive or skip them.

​
Use the TUI

Main list

j / k or arrow keys move through events. g or home jumps to the top; G or end jumps to the bottom. ctrl+l clears the local list.

Request details

Press space to open or close details. The detail view shows request headers, body, response headers, response body, status, target, and duration.

Copy context

Press c to copy the selected event or detail view for debugging.

Generate types

Press t to generate typed definitions from the selected request body.

​
Generate types

Type generation uses the selected event’s JSON request body. It is available only when the selected request has a JSON body.
KeyAction
tOpen the generate-types overlay.
h / l or arrow keysSwitch target language.
tabEdit the type name. The default is WebhookPayload.
oOpen generation options.
space / enterToggle an option, cycle a value, or commit an edited value.
cCopy the generated code.
escClose the overlay.
The CLI remembers the preferred language and common generation options in its config directory. Empty or older config files fall back to the default generation options.

​
Local request behavior

Headers

The CLI forwards request headers but removes hop-by-hop and computed headers such as Host, Content-Length, Connection, and Transfer-Encoding.

Timeouts

Requests use the forwarder’s configured timeout. If no timeout is configured, the local request limit is 60 seconds.

Success

A local HTTP response is marked successful when the destination returns a 2xx status code. Other HTTP responses are recorded with their status and body.

Response capture

The normal forwarding path captures up to 1 MB of response body for inspection.

Proxy replies

For proxy buckets, the CLI sends the local response back to Repost. Reply bodies returned to the provider are capped at 512 KB.

Connection failures

Timeouts, connection errors, invalid targets, and response-read failures are reported as failed local deliveries.

​
Headless sessions

--headless connects without the terminal UI. It prints HEADLESS_READY after the WebSocket listener is established, then processes incoming events in the background. 
repost forward \
  --bucket-slug stripe-prod \
  --forwarder local-webhooks \
  --skip-pending \
  --headless
For automation, pass --skip-pending so startup does not wait on an interactive pending-event decision.

​
Common fixes

Run repost auth login for browser auth, or set REPOST_TOKEN for an API token based workflow.
Run repost bucket list and use the bucket slug from the dashboard. repost forward expects a slug, not a bucket ID.
Create an internal forwarder on the bucket. External forwarders are managed by Repost and do not need a local CLI listener.
Only one active CLI session can own the same listener context at a time. Close the other session or reconnect from the terminal you want to use.