Skip to main content

Local Development with the Dispatch CLI

The dispatch CLI lets you forward incoming webhook events to a server running on your local machine. This means you can receive real webhooks from GitHub, Stripe, or any other service without exposing a public URL — perfect for local development and testing.

How It Works​

When dispatch listen is running, events arriving at your Dispatch endpoint are forwarded over a secure tunnel to http://localhost:<port>. Your local server handles the request and returns a response. The response is recorded and visible in the Events tab of the dashboard, giving you a full audit trail even during local development.

Events are only forwarded while the CLI is connected. Events that arrive when the CLI is not running are not buffered — reconnecting starts forwarding new events from that point onward.

Installation​

npm install -g @dispatch/cli

Requires Node.js 18 or later. Pre-compiled binaries for Linux, macOS, and Windows are downloaded automatically — no Go toolchain needed.

Via Go​

go install github.com/dispatch-services/dispatch/packages/cli/cmd/dispatch@latest

Ensure $GOPATH/bin is on your PATH.

Authenticate​

dispatch login

You will be prompted for your Dispatch email and password. To use GitHub or Google instead:

dispatch login --oauth

Your credentials are never stored. Only the session tokens are saved to ~/.dispatch/config.json (file permissions 0600).

Start Listening​

dispatch listen 3000

An interactive picker lets you choose your organization, project, and webhook source. Once connected, the terminal shows a live stream of forwarded events:

  Listening on  my-github-source → localhost:3000/

  Connected.

  → POST  push          200  42ms
  → POST  pull_request  200  11ms

Specify a source directly​

dispatch listen 3000 my-github-source

Forward to a specific path​

dispatch listen 3000 my-github-source --path /api/webhooks

Events are POSTed to http://localhost:3000/api/webhooks.

Skip the project picker (useful in scripts)​

dispatch listen 3000 my-source-slug --project proj_abc123

Keyboard Shortcuts While Listening​

KeyAction
rReplay the last received event
pPause / resume forwarding
cChange source, transform, template, or delay
hPrint keyboard shortcut help
q / Ctrl+CExit

Interactive Picker​

The picker walks through org → project → source. Press Esc or Backspace to go back one level. If you have only one org and one project, those steps are skipped automatically.

After selecting a source, you are offered optional settings:

  • Transform — apply a named JSONata transform to the payload before it is forwarded
  • Template — apply a message template
  • Delivery delay — introduce a deliberate delay before forwarding (useful for testing timeout handling)

CLI Destination in the Dashboard​

Every dispatch listen session creates (or reuses) a CLI destination in your project. It appears on the Destinations page as:

CLI · alice@my-laptop · my-source-slug

This is how Dispatch knows where to forward events. You can safely ignore or delete these destinations — the CLI recreates them automatically on next run.

Configuration File​

The CLI stores its state at ~/.dispatch/config.json. You can inspect the api_url field to confirm which Dispatch instance you are connected to.

Common Error Messages​

MessageWhat to do
not logged in — run 'dispatch login' firstRun dispatch login.
invalid port: <value>Use a number between 1 and 65535.
could not reach Dispatch API at <url>Check your network or --api-url.
no sources foundCreate a webhook source in the dashboard first.
refresh failedYour session expired — run dispatch login again.