Sources Listen Command Reference

This page is a detailed reference for the rudder-cli sources commands. sources listen runs a local server that accepts events the way RudderStack ingestion does and prints each accepted event on stdout. sources events reads the events a listener keeps in memory.

For a step-by-step walkthrough with examples, see How to Verify App Events Locally.

Experimental feature

The sources commands are experimental and disabled by default. You must enable experimental mode and the sourcesListen flag before you run them. Experimental features are functional but their commands, flags, and output can change or be removed in future releases, so avoid relying on them in production workflows.

Overview

The listener needs no access token, no workspace, and no network. It does not deliver events to destinations, run transformations, or validate events against a Tracking Plan.

Enable the experimental flag

The sources commands require two settings:

1. Experimental mode (experimental): The main switch for all experimental features.
2. The sourcesListen flag: Turns on the sources commands.

If either is disabled, every sources command exits with code 1 and the error code experimental_disabled. The message names both environment variables.

{
  "experimental": true,
  "flags": {
    "sourcesListen": true
  }
}

rudder-cli experimental enable sourcesListen
rudder-cli experimental list

export RUDDERSTACK_CLI_EXPERIMENTAL=true
export RUDDERSTACK_X_SOURCES_LISTEN=true

rudder-cli sources --help prints the full user guide for these commands, and does not need the flag.

Start a listener

Command syntax

rudder-cli sources listen [flags]

Parameters

Description

sources listen runs in the foreground until it receives SIGINT (Ctrl+C) or SIGTERM. It then finishes the requests in progress and exits with code 0. To run it in the background, use your shell’s & and stop it with kill <pid>.

The listener answers every route an SDK calls:

• The ingestion routes /v1/track, /v1/identify, /v1/page, /v1/screen, /v1/group, /v1/alias, /v1/batch, /v1/merge, /v1/import, /v1/audiencelist, /beacon/v1/batch, /pixel/v1/track, and /pixel/v1/page, with RudderStack’s status codes and error messages.
• /sourceConfig, with a fixed source configuration that has no destinations, so browser and mobile SDKs finish loading.
• CORS preflights and the health routes.

Output

The listener writes two streams:

The ready line is one JSON object that the listener prints once the port accepts connections:

{"ready":true,"apiVersion":"v1","serverId":"225d1f4623d83972","url":"http://127.0.0.1:4321","port":4321,"bind":"127.0.0.1","pid":66751,"startedAt":"2026-10-14T17:14:57Z","writeKey":"dev","writeKeyPolicy":"any"}

A refused line looks like this:

refused: 400 POST /v1/track: invalid json
refused: 401 POST /v1/batch: invalid write key
refused: 401 POST /v1/track: failed to read writekey from header

A pixel request answers 200 even when its event is dropped. It still prints a refused: line.

Examples

• Print events as they arrive:

rudder-cli sources listen --port 4321

• Show only one event name:

rudder-cli sources listen --port 4321 | grep '"event":"Order Completed"'

• Run in the background, with the events and the log in files:

rudder-cli sources listen --port 0 > events.ndjson 2> listen.log &

• Accept only two write keys:

rudder-cli sources listen --port 4321 --write-key web-key --write-key api-key

• Keep requests in memory for sources events and the review page:

rudder-cli sources listen --port 4321 --store

Read stored events

Command syntax

rudder-cli sources events --url <listener-url> [flags]

Parameters

Different flags combine with AND. A repeated flag combines with OR.

Description

sources events reads from a listener started with --store. Without --store, it fails with store_disabled. With --json, each line is an accepted event exactly as the SDK sent it, the same lines the listener prints on stdout. When more events are left than --limit allows, stderr prints more events: continue with --since N, and stdout stays pure.

Examples

• The properties of one event:

rudder-cli sources events --url http://127.0.0.1:4321 --event 'Order Completed' --fields properties --json

• A table of what arrived in the last five minutes:

rudder-cli sources events --url http://127.0.0.1:4321 --since 5m

• Events without the auto-collected context:

rudder-cli sources events --url http://127.0.0.1:4321 --view compact --json

Query API

A listener started with --store serves a read-only HTTP API on the same port, under /_dev/v1/. Use it from a test process in any language.

Every GET route also answers HEAD.

The query API has no authentication. It accepts only requests whose Host is localhost, an address in 127.0.0.0/8, the bound IP, or a name passed with --allow-host. It sends no CORS headers and refuses cross-site browser requests, so a web page cannot read captured events. Call it from a shell or a test process, never from inside the page under test.

Records never keep Authorization or cookie headers. A write key longer than 8 characters appears masked.

Review page

A listener started with --store serves a read-only web page at the ui URL from the ready line. It shows the captured events and requests, filters by event name and write key, searches payload values, and explains why events are missing. It loads nothing from the network.

Limits and differences from RudderStack

A passing check is strong evidence that the app instruments events correctly, not a guarantee. The listener answers with RudderStack’s status codes and messages, and adds limits of its own:

• A request body is at most 2,048,000 bytes, raw and decoded, and a batch has at most 10,000 events. Larger requests get 413.
• At most 8 requests are read at once. More get 503. A body that takes over 10 seconds to arrive is refused.
• With --store, the listener keeps the last 10,000 requests or 64 MiB, and drops the oldest whole requests first.
• It does not check the 32 KB per-event limit or the JSON depth limit.
• It does not deliver events, run transformations, or validate events against a Tracking Plan.
• If a reader stops reading stdout, the SDK’s request waits until it reads again.

Error codes

Errors print on stderr with a Next: command that fixes them. With --json, an error is one JSON object with error.code and error.next. Every command exits with code 0 on success and 1 on an error.

See more

• How to Verify App Events Locally: The local loop, SDK setup, agents, and CI recipes.
• Install Rudder CLI: Install the CLI and its Docker image.
• Live Events: Check the events a workspace source receives after you deploy.