Local forwarding

Connect internal forwarders to localhost, handle pending events, and inspect live webhook traffic from the Repost CLI.

Local forwarding is the CLI workflow for receiving real webhook traffic on your machine.

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.

Interactive

Run without flags to choose the bucket and forwarders from prompts.

repost forward

Scripted

Use a bucket slug and one or more forwarder names.

repost forward \
  --bucket-slug stripe-prod \
  --forwarder local-webhooks

Multiple forwarders

Repeat --forwarder to listen to more than one internal forwarder in the same bucket.

repost forward \
  -b stripe-prod \
  -f local-api \
  -f local-worker

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.

Prompt

Default behavior. The TUI asks how to handle pending events before it starts real-time delivery.

repost forward -b stripe-prod -f local-webhooks

Pending first

Drain waiting events first, then continue with new events.

repost forward -b stripe-prod -f local-webhooks --pending-first

Skip pending

Mark waiting events as skipped for this session and receive only new events.

repost forward -b stripe-prod -f local-webhooks --skip-pending

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 models from the selected request body.

Generate types

Press t on an event with a JSON body to turn it into typed models — choose a language, name the output, and tune inference and renderer options. See Generate types for the full walkthrough.

Automation

Running this in CI or a deploy script instead of at your desk? See CI & automation for headless forwarding, environment-token auth, and pausing forwarders during a deploy. Local delivery details — header handling, timeouts, and response caps — are in the command reference.

Common fixes

The CLI says I am not authenticated

Run repost auth login for browser auth, or set REPOST_TOKEN for an API token based workflow.

The bucket slug is not found

Run repost bucket list and use the bucket slug from the dashboard. repost forward expects a slug, not a bucket ID.

No internal forwarders appear

Create an internal forwarder on the bucket. External forwarders are managed by Repost and do not need a local CLI listener.

Another session took over

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.