Forward Live Webhooks to Your Local Machine with Repost

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:

CLI installed and authenticated

Install the binary and run repost auth login or set REPOST_TOKEN. See Authentication if you haven’t done this yet.

An internal forwarder

repost forward only attaches to internal forwarders. Create one on a queued bucket in the Repost dashboard before running the command.

A running local endpoint

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.

Interactive
Scripted
Multiple forwarders

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 forward

Pass --bucket and --forwarder to skip the prompts entirely. This is useful in scripts and repeated workflows.

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

Repeat --forwarder (or -f) to attach to more than one internal forwarder in the same bucket at the same time.

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

If 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.

Prompt (default)
Pending first
Skip pending

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-webhooks

Drain all queued events first, then seamlessly continue with new events as they arrive.

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

Mark all queued events as skipped for this session and receive only new events going forward.

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

Do 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-pending

Combine --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.

Next steps

Reference

See all commands, flags, TUI shortcuts, and environment variables in the complete CLI reference.

Authentication

Review authentication methods and credential priority if you are setting up the CLI for CI or a new machine.

​Prerequisites

CLI installed and authenticated

An internal forwarder

A running local endpoint

​Start a forwarding session

​Handle pending events

​Use the TUI

​Event list

​Detail panel

​Generate types panel

​Quit

​Run in headless mode

​Internal forwarder state

​Common fixes

​Next steps

Reference

Authentication

Prerequisites

Start a forwarding session

Handle pending events

Use the TUI

Event list

Detail panel

Generate types panel

Quit

Run in headless mode

Internal forwarder state

Common fixes

Next steps