Local forwarding is how the Repost CLI delivers real webhook traffic to a service running on your machine. When you run repost forward, the CLI attaches to one or more internal forwarders, streams incoming events to your local HTTP endpoint, and shows request and response details in an interactive terminal UI.
Prerequisites#
Before starting a forwarding session, make sure you have the following in place:
Install the binary and run repost auth login or set REPOST_TOKEN. See Authentication if you haven't done this yet.
repost forward only attaches to internal forwarders. Create one on a queued bucket in the Repost dashboard before running the command.
Your application must be running and listening at the target URL configured on the internal forwarder.
Start a forwarding session#
repost forward resolves a bucket first, then resolves internal forwarders inside that bucket.
Run with no flags. The CLI prompts you to select a bucket from your account, then prompts you to pick one or more internal forwarders from that bucket.
repost forwardIf you provide --bucket or --forwarder, provide both. Partial flag usage is rejected so the CLI never connects to an ambiguous target.
--bucket expects a bucket slug for local forwarding. --bucket-slug remains accepted as a compatibility alias. --forwarder expects an internal forwarder name. External forwarders are filtered out because they are delivered by Repost.
Handle pending events#
When a forwarder has events queued up from before your session started, the CLI can ask what to do, drain the queue first, or skip it entirely and jump straight to new traffic.
Without any pending-event flag, the TUI asks per forwarder whether to receive or skip pending events before starting real-time delivery.
repost forward -b stripe-prod -f local-webhooksDo not combine --pending-first and --skip-pending. If both flags are present, --skip-pending takes precedence and queued events are skipped.
Use the TUI#
The terminal UI shows a live stream of forwarded events. Each row displays the event status, response code, target, and duration. Use the following shortcuts to navigate and inspect traffic.
Event list#
| Key | Action |
|---|---|
j / k or arrow keys | Move selection up and down. |
g / Home | Jump to the top of the list. |
G / End | Jump to the bottom of the list. |
Space | Open the detail panel for the selected event. |
c | Copy the selected row context for debugging. |
t | Generate types from the selected JSON request body. |
Ctrl+L | Clear all local rows from the view. |
Detail panel#
Press Space on any event to open its detail panel. The panel shows request headers, request body, response headers, response body, status code, target URL, and duration.
| Key | Action |
|---|---|
Space or Esc | Close the detail panel. |
c | Copy the detail view. |
t | Generate types from the request body. |
Generate types panel#
Press t on any event with a JSON body to open the type generation panel. You can switch language, rename the root type, and toggle inference options without leaving the terminal.
| Key | Action |
|---|---|
h / l or arrow keys | Switch between supported languages. |
Tab | Edit the root type name. |
o | Open the options panel. |
Space / Enter | Toggle an option, cycle a value, or commit an edited value. |
c | Copy the generated code. |
Esc | Close the generate types panel. |
Quit#
Press q or Ctrl+C from any view to end the forwarding session and exit the CLI.
Run in headless mode#
Use --headless when you want repost forward to run without the terminal UI, for example in CI pipelines or test scripts. In headless mode, the CLI prints HEADLESS_READY to stdout after the connection is fully set up, which you can use as a signal in scripts.
repost forward \
-b stripe-prod \
-f local-webhooks \
--headless \
--skip-pendingCombine --headless with --skip-pending in automation so the CLI does not pause to ask about pending events. The process starts forwarding new events immediately after printing HEADLESS_READY.
Internal forwarder state#
An internal forwarder starts in a paused state until the CLI connects to it. Once you run repost forward, the forwarder becomes active and begins delivering events. If your CLI session disconnects, the forwarder returns to a paused state and holds new events until you reconnect.
Reconnecting is as simple as running repost forward again with the same flags. The Repost dashboard shows No listeners on the forwarder card when no CLI session is currently connected.
Common fixes#
The CLI says I am not authenticated
Run repost auth login to sign in through the browser, or set REPOST_TOKEN to an API token from your Repost dashboard. See Authentication for details.
The bucket slug is not found
Run repost bucket list to see the exact slug for each bucket in your account. The --bucket flag expects the slug value from the SLUG column, not the bucket ID or display name.
No internal forwarders appear
Only internal forwarders are available to repost forward. If you only have external forwarders on a bucket, create an internal forwarder in the Repost dashboard first.
Another session took over
Only one active CLI session can own a given forwarder at a time. Close the other session and run repost forward again from the terminal you want to use.