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

Via npm (recommended)

npm install -g @dispatch.tech/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

An interactive picker lets you choose how to sign in:

Select a login method:
  ► Email and password
    Continue with GitHub  (opens browser)
    Continue with Google  (opens browser)

To skip the picker and go straight to a browser-based flow, pass --provider:

dispatch login --provider github
dispatch login --provider google

Only session tokens are saved to ~/.dispatch/config.yaml (file permissions 0600). Passwords and OAuth secrets are never stored.

Log Out

dispatch logout

Clears stored credentials from ~/.dispatch/config.yaml. Run dispatch login again to re-authenticate.

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

Key	Action
r	Replay the last received event
p	Pause / resume forwarding
c	Change source, filter, transform, template, or delay
h	Print keyboard shortcut help
q / Ctrl+C	Exit

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:

• Filter — apply a named filter to only forward events that match its conditions
• 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

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 in ~/.dispatch/config.yaml. You can run dispatch config to see which files are active and which URLs are in use:

dispatch config

Per-project credentials

If you work across multiple accounts or want to commit a project-specific API URL, you can log in with --local:

dispatch login --local

This saves credentials to .dispatch.yaml in the current directory instead of the global config. Make sure to add .dispatch.yaml to your .gitignore.

Per-project credentials take precedence over the global config.

Check Your Version

dispatch version

Common Error Messages

Message	What to do
not logged in — run 'dispatch login' first	Run dispatch login.
invalid port: <value>	Use a number between 1 and 65535.
could not reach Dispatch API at <url>	Check your network connection.
no sources found	Create a webhook source in the dashboard first.
refresh failed	Your session expired — run dispatch login again.