# How to Verify App Events Locally with Rudder CLI

Unit tests can assert that your code calls track, and Tracking Plan validation checks your YAML. Neither proves that the running app sends the right event, with the right properties, to a data plane. rudder-cli sources listen closes that gap on your machine. It accepts events the way RudderStack ingestion does and prints each accepted event as one JSON line, so you can check it with grep and jq.

You need no access token, no workspace, and no network. The same loop works at a terminal, in CI, and for a coding agent.

Experimental feature

sources listen is experimental and disabled by default. You must enable the experimental flag first. Its commands, flags, and output can change or be removed in future releases, so avoid relying on them in production workflows.

When to use local verification

You want to check Use
That a click, a page view, or a code path sends the expected event with the expected properties sources listen (this guide)
That your Data Catalog and Tracking Plan YAML is valid rudder-cli validate
What a workspace source received after you deploy, and whether it was delivered Live Events

The listener stops at capture. It does not deliver events to destinations, run transformations, or validate events against a Tracking Plan.

Prerequisites

Step 1: Enable the experimental flag

In the shell where you run the listener, export both variables:

shell 
export RUDDERSTACK_CLI_EXPERIMENTAL=true
export RUDDERSTACK_X_SOURCES_LISTEN=true

To save the setting instead, see Enable the experimental flag.

Step 2: Start the listener

Start the listener on a fixed port, with the events in one file and the log in another:

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

The first line of listen.log is the ready line:

json 
{"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"}

The url is what your app sends to. To watch events live in a terminal instead, run rudder-cli sources listen --port 4321 in the foreground and leave the window open.

Vite, Next.js, and mobile builds read the data plane URL at build or start time. For those apps, start the listener first, then start or rebuild the app.

Step 3: Point your app at the listener

Set the SDK’s data plane URL to the url from the ready line. Any write key works, so use dev. SDKs that fetch their source configuration also need the config URL set to the same url. Without it, they call RudderStack’s production servers.

Set configUrl to the listener. Import the bundled build so the SDK does not load its plugins from the CDN:

javascript 
import { RudderAnalytics } from '@rudderstack/analytics-js/bundled';

const analytics = new RudderAnalytics();
analytics.load('dev', 'http://127.0.0.1:4321', {
  configUrl: 'http://127.0.0.1:4321'
});
analytics.track('Order Completed', { total: 42 });

Chrome blocks a page served over public HTTPS from sending to a loopback address. Serve the app from a local http:// origin, such as http://localhost:3000.

See Loading options for configUrl.

Other SDKs follow the same rule: set the data plane URL, and for mobile SDKs the control plane URL, to the listener. Java takes the base URL only. Ruby and PHP need TLS turned off (use_ssl: false or ssl: false in Ruby, ssl => false in PHP), and PHP needs the lib_curl or fork_curl consumer.

Step 4: Trigger the events

Use the app: click the button, load the page, or run the test or script that exercises the code path. Before you check, decide which events each action should send and how many. For example, one click on Buy sends one Order Completed.

Step 5: Check the events

Each line in events.ndjson is one accepted event with its whitespace removed. Wait for the event, then check it:

shell 
# wait up to 20 seconds for the event
for i in $(seq 100); do grep -q '"event":"Order Completed"' events.ndjson && break; sleep 0.2; done

# exactly one Order Completed
jq -e -s '[.[] | select(.event == "Order Completed")] | length == 1' events.ndjson

# every total is a number; length > 0 fails when nothing arrived
jq -e -s '[.[] | select(.event == "Order Completed")] | length > 0 and all(.[]; .properties.total | type == "number")' events.ndjson

# the properties of each Order Completed
jq -c 'select(.event == "Order Completed") | .properties' events.ndjson

# a count by event name
jq -r '.event // .type' events.ndjson | sort | uniq -c

jq -e exits with 0 when the check is true and 1 when it is false, so the same lines work as assertions in a script.

Use jq -s to read the file as one array. Without it, jq -e decides on the last line only. Keep the length > 0 guard, because all() over zero events is true.

Check for refused requests

A refused request never reaches events.ndjson, so a missing event can be a refused one. Each refused ingestion request prints one line in listen.log. Configuration calls and CORS preflights never print one:

shell 
grep '^refused:' listen.log
refused: 400 POST /v1/track: request neither has anonymousId nor userId
refused: 401 POST /v1/batch: invalid write key

When the file has no refused: lines and the event is still missing, the app is not sending to the listener. With --write-key, the listener can also have refused the SDK’s configuration call. A refused /sourceConfig call prints no refused: line, and a browser SDK that cannot load its configuration sends no events. To list refused configuration calls, start the listener with --store and run:

shell 
curl -fsS "http://127.0.0.1:4321/_dev/v1/requests?kind=control&failed=true"

See Troubleshooting for more causes.

Step 6: Stop the listener

shell 
kill %1

Use kill <pid> with the pid from the ready line when the listener runs in another shell. The listener exits with code 0, and the two files stay.

Inspect requests with –store

The stdout lines answer most questions. Start the listener with --store when you also need:

shell 
rudder-cli sources listen --port 4321 --store > events.ndjson 2> listen.log &

The ready line then includes cursor and ui. Read stored events with sources events:

shell 
# 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 the last five minutes
rudder-cli sources events --url http://127.0.0.1:4321 --since 5m

# why requests were refused
curl -fsS "http://127.0.0.1:4321/_dev/v1/requests?failed=true&view=compact"

# the SDK's configuration calls and preflights
curl -fsS "http://127.0.0.1:4321/_dev/v1/requests?kind=control"

Open the ui link from the ready line to review events and requests in a browser. The store keeps the last 10,000 requests or 64 MiB. For every flag and route, see the Sources Listen Command Reference.

Verify events with a coding agent

A coding agent can run the whole loop: change the tracking code, start the listener, exercise the app, and read what was sent. Two rules keep an agent’s shell from hanging:

This script does all four steps in one call:

shell 
set -euo pipefail
export RUDDERSTACK_CLI_EXPERIMENTAL=true RUDDERSTACK_X_SOURCES_LISTEN=true
d=$(mktemp -d)
rudder-cli sources listen --port 0 >"$d/events" 2>"$d/log" &
pid=$!; trap 'kill "$pid" 2>/dev/null' EXIT
until grep -q '^{"ready":true' "$d/log"; do kill -0 "$pid" 2>/dev/null || { cat "$d/log" >&2; exit 1; }; sleep 0.1; done
url=$(grep -m1 '^{"ready":true' "$d/log" | jq -r .url)

RUDDERSTACK_DATA_PLANE_URL="$url" node scripts/checkout-smoke.js

for i in $(seq 100); do grep -q '"event":"Order Completed"' "$d/events" && break; sleep 0.2; done
jq -c 'select(.event == "Order Completed") | .properties' "$d/events"
grep '^refused:' "$d/log" || true

rudder-cli sources --help prints the full guide, so an agent can read it from the binary it is using.

Verify events in CI

Run the listener inside the job, act, then assert on the file. On a failure, the trap prints the listener’s log, refusals included, to the job log.

yaml 
jobs:
  tracking:
    runs-on: ubuntu-latest
    env:
      RUDDERSTACK_CLI_EXPERIMENTAL: "true"
      RUDDERSTACK_X_SOURCES_LISTEN: "true"
      RUDDERSTACK_CLI_TELEMETRY_DISABLED: "true"
      RUDDERSTACK_DATA_PLANE_URL: http://127.0.0.1:4321
      RUDDERSTACK_CONFIG_URL: http://127.0.0.1:4321
      RUDDERSTACK_WRITE_KEY: dev
    steps:
      - uses: actions/checkout@v4  # pin actions to a commit SHA in your repository
      # install rudder-cli and jq, then install and build the app with the env above
      - name: Capture, act, check
        shell: bash
        run: |
          set -euo pipefail
          d=$(mktemp -d)
          rudder-cli sources listen --port 4321 >"$d/events" 2>"$d/log" &
          pid=$!
          trap 'rc=$?; [ "$rc" -eq 0 ] || cat "$d/log" >&2; kill "$pid" 2>/dev/null; exit "$rc"' EXIT
          until grep -q '^{"ready":true' "$d/log"; do kill -0 "$pid" 2>/dev/null || { cat "$d/log" >&2; exit 1; }; sleep 0.1; done

          npx playwright test tracking.spec.ts --workers=1

          for i in $(seq 150); do grep -q '"event":"Order Completed"' "$d/events" && break; sleep 0.2; done
          jq -e -s '[.[] | select(.event == "Order Completed")] | length == 1' "$d/events"
          jq -e -s '[.[] | select(.event == "Order Completed")] | all(.[]; .properties.total | type == "number")' "$d/events"
          if grep '^refused:' "$d/log"; then exit 1; fi
Keep set -euo pipefail at the top of the script. A script that a step calls does not inherit the step’s options, so a failed jq -e in it would not fail the job. Do not write a check as ! grep ...: set -e ignores a command that starts with !. Use if grep ...; then exit 1; fi instead.

Take the expected event names and property values from your Tracking Plan YAML or your test, never from the captured events. The recipe uses POSIX shell tools and Unix signals, so run it on Linux or macOS runners.

Check events from a test file

A test can read the same file. Start the listener before the test runner and pass the file path in an environment variable, such as EVENTS:

typescript 
import { test, expect } from '@playwright/test';
import { readFileSync } from 'node:fs';

const file = process.env.EVENTS ?? 'events.ndjson';
const lines = () => readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
const named = (name: string) => lines().filter((e) => e.event === name);

test('a purchase sends Order Completed once, with a numeric total', async ({ page }) => {
  const before = named('Order Completed').length;
  await page.goto('/');
  await page.getByRole('button', { name: 'Buy' }).click();
  await expect.poll(() => named('Order Completed').length, { timeout: 30_000 }).toBe(before + 1);
  for (const e of named('Order Completed').slice(before)) {
    expect(typeof e.properties.total).toBe('number');
  }
});

The file only grows, so count from its length before the action. For parallel workers, give each test its own anonymousId and filter on it.

Run the listener in Docker

The rudderlabs/rudder-cli image runs the listener when you pass the command. Bind to 0.0.0.0 inside the container and publish the port on your machine’s loopback only:

shell 
docker run -d --name sources-listen -p 127.0.0.1:4321:4321 \
  -e RUDDERSTACK_CLI_EXPERIMENTAL=true -e RUDDERSTACK_X_SOURCES_LISTEN=true \
  rudderlabs/rudder-cli:<version> sources listen --bind 0.0.0.0 --port 4321

# wait for the ready line on the container's stderr
until docker logs sources-listen 2>&1 | grep -q '^{"ready":true'; do sleep 0.2; done

# after the app ran: the events are the container's stdout
docker logs sources-listen 2>/dev/null > events.ndjson

Use an image tag that includes the sources commands. A bare -p 4321:4321 opens the port on every network interface of your machine. With --store, a container that reaches the listener by a service name needs --allow-host <name>, or the query API answers 403. GitHub Actions services: cannot pass a command to an image, so start the container in a run: step.

Troubleshooting

Problem Cause and fix
experimental_disabled Export RUDDERSTACK_CLI_EXPERIMENTAL=true and RUDDERSTACK_X_SOURCES_LISTEN=true in the same shell.
port_in_use Another process holds the port. Use another --port, or --port 0 and read the port from the ready line.
The shell or agent call hangs The listener runs in the foreground. Start it with & and redirect stdout and stderr to files.
Nothing in events.ndjson and no refused: lines The app does not send to the listener. Check the data plane URL, the config URL, and any code that turns analytics off in development, then restart the app. Send the cURL event from Step 3 to confirm the listener works.
A browser app sends nothing Without configUrl, the JavaScript SDK fetches its configuration from RudderStack’s servers. Set configUrl to the listener. Serve the app over http://, not public HTTPS.
The browser requests cdn.rudderlabs.com The default JavaScript SDK build loads plugins from the CDN. Import @rudderstack/analytics-js/bundled to stay offline.
A Node.js or Go script exits and nothing arrives The SDK buffers events. Call flush() or Close() before the process exits.
refused: 401 lines, or no events from a browser or mobile SDK while the listener runs with --write-key The app sends another key or none. The ingestion routes answer 401 and print a refused: line. /sourceConfig answers 401 to a missing key and 400 to a key that is not allowed, and prints no line. Use an allowed key, or start without --write-key.
refused: 400 lines The body is not a valid event: invalid JSON, an empty batch, or an event with neither userId nor anonymousId. Start with --store and read the raw body from /_dev/v1/requests.
sources events fails with store_disabled The listener was started without --store. Restart it with --store, or read its stdout file.
grep '"event": "X"' finds nothing The lines have no spaces. Use grep '"event":"X"', or jq.

See more