Skip to content

Sparrow CLI

The sparrow CLI is the fastest way to work with a Sparrow server: push test events, watch deliveries stream by, receive webhooks on your laptop, and debug transform templates without a single curl invocation.

The easiest way — no Go toolchain needed — is the install script. It picks the prebuilt binary for your OS and architecture from the latest release, verifies its SHA-256 against the release’s checksums.txt, and puts sparrow in /usr/local/bin (or ~/.local/bin when that is not writable):

Terminal window
curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh | sh
sparrow version

Updating is the same command: it finds the sparrow already on your PATH, replaces it in place with the requested release, and downloads nothing when it is already at that version (-f reinstalls anyway).

Flags (pass them with sh -s -- ...) or environment variables pin a version or change the destination:

Terminal window
curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh | sh -s -- -v v1.0.0 -b ~/bin
SPARROW_VERSION=v1.0.0 SPARROW_INSTALL_DIR=~/bin sh install.sh # same thing
sh install.sh -c server # the server binary (sparrow-server) instead of the CLI
sh install.sh -f # reinstall the current version

Prebuilt binaries are published for macOS and Linux (amd64 + arm64) and Windows (amd64). On Windows, download the sparrow-cli .zip from the release page and put sparrow.exe on your PATH; or extract any archive by hand:

Terminal window
# e.g. macOS arm64: sparrow-cli-<version>-darwin-arm64.tar.gz
tar xzf sparrow-cli-*.tar.gz
sudo mv sparrow /usr/local/bin/

Have a Go toolchain? Install straight from source instead:

Terminal window
go install github.com/sarathsp06/sparrow/satellites/sparrow@latest
Terminal window
# 1. Point the CLI at your server (writes ~/.sparrow/config.yaml)
sparrow init --url http://localhost:8080
# 2. Receive deliveries locally: registers a temporary webhook,
# prints every delivery, deletes the webhook on Ctrl-C
sparrow listen --event order.created
# 3. In another terminal: push an event
# (the event type is registered first if it doesn't exist yet)
sparrow push order.created -d '{"order_id":"ord_1","amount":42}'

The delivery shows up in the listen terminal, signature-verified, headers and body pretty-printed.

The CLI is a pure REST client — the same public API you can call with curl, authenticated with X-API-Key when a key is configured. It holds no state on the server beyond what the API calls create. Every subcommand maps to plain endpoints:

Command API calls
init GET /health (probe; falls back to GET /v1/event-types?limit=1), then writes ~/.sparrow/config.yaml locally
push POST /v1/consumers/{consumer}/events?event=<name>; on 404 or 422, POST /v1/event-types and one retry
events GET /v1/event-types?consumer=<consumer> (list) or GET /v1/event-types/{name} (detail)
events export/import POST /v1/event-types:export / POST /v1/event-types:import
webhooks GET /v1/consumers/{consumer}/webhooks (list or detail) plus subscriptions
tail deliveries GET /v1/consumers/{consumer}/deliveries every 2 s, printing rows not seen before
listen POST /v1/consumers/{consumer}/webhooks (temporary registration) … DELETE on Ctrl-C
use POST /v1/consumers/{consumer}/webhooks, then PATCH subscriptions to attach the recipe’s transform and label filters
stats GET /v1/consumers/{consumer}/stats
functions GET /v1/template-functions
tokens POST /v1/tokens, GET /v1/tokens, DELETE /v1/tokens/{id}
invite / invites POST /v1/invites, GET /v1/invites, DELETE /v1/invites/{id}
template test none — renders locally with the same Go template engine the server uses

listen is the one command with a receiving side. Its technical path:

1. bind a local TCP port (random unless --port; bind address: --bind, default all interfaces)
2. POST /v1/consumers/{consumer}/webhooks
url = --public-url, default http://host.docker.internal:<port>
→ response contains the webhook secret (shown once)
3. serve HTTP: for each delivery from Sparrow's worker
- verify the Standard Webhooks headers (webhook-id, webhook-timestamp,
webhook-signature) against that secret — HMAC-SHA256 over
"{id}.{timestamp}.{body}"
- unsigned or mis-signed requests get 401 and are never forwarded
- request bodies are capped at 5 MiB
- pretty-print headers + body, or proxy to --forward and mirror its status
4. Ctrl-C → DELETE the temporary webhook

--bind controls the listen address: the default is all interfaces (so a Dockerized server can reach it); use --bind 127.0.0.1 for loopback only.

Because the server delivers to the CLI here, the server must be allowed to reach your machine: the host.docker.internal default covers a Dockerized server on the same host (with SPARROW_ALLOW_PRIVATE_NETWORKS=true or the local evaluation Compose file); use --public-url with a tunnel for a remote server.

sparrow init writes ~/.sparrow/config.yaml (mode 0600):

server_url: http://localhost:8080
api_key: "" # sent as X-API-Key when set
consumer: default

Every value can be overridden — precedence is environment > flags > config file:

Env var Flag Config key
SPARROW_URL --url server_url
SPARROW_API_KEY --api-key api_key
SPARROW_CONSUMER --consumer consumer

For each setting the first non-empty source wins, in that order, then the built-in default (http://localhost:8080, consumer default). Note that an environment variable beats a flag on the same command line: with SPARROW_URL exported, --url is ignored, so unset the variable to use the flag. SPARROW_API_KEY is also the server’s master-key variable, so a shell that runs the server hands the same key to the CLI. SPARROW_CONFIG points the CLI at another config file instead of ~/.sparrow/config.yaml.

Probes the server (GET /health, falling back to GET /v1/event-types?limit=1) and writes the config file. Interactive when run in a terminal; fully scriptable with flags. Idempotent — re-running overwrites the file.

Terminal window
sparrow init --url https://sparrow.example.com --api-key $KEY --consumer payments

Pushes one event occurrence and prints its event ID. If the server answers 404 or 422 (the event type isn’t registered), the CLI registers the type, prints event type "<name>" auto-created, and retries the push once. Registering needs the master key or a tenant-wide token; if it fails, the CLI prints both errors. Names starting with sparrow. are reserved and can’t be pushed.

Terminal window
sparrow push order.created -d '{"order_id":"ord_1"}' # inline JSON
sparrow push order.created -d @payload.json # from a file
sparrow push order.created -l env=prod -l region=eu # labels for label_filters
sparrow push order.created --idempotency-key ord_1-created # dedup: same key returns the original event id

Lists event types with their current version, or shows one type’s schema and sample payload.

The list shows the event types your consumer can subscribe to. Sparrow’s own sparrow.webhook.* event types appear only with --consumer _sparrow, the one consumer that can subscribe to them (and that can’t subscribe to anything else): sparrow --consumer _sparrow events. See Webhook health alerts.

Terminal window
sparrow events # every event type
sparrow events --active # only active event types
sparrow events order.created # one type's detail
sparrow events versions order.created
sparrow events -o json # machine-readable output

sparrow events export and sparrow events import

Section titled “sparrow events export and sparrow events import”

Move event type definitions between environments as one JSON bundle. See Moving Event Types Between Environments.

Terminal window
# export by name, by prefix, or everything (stdout by default)
sparrow events export order.created order.shipped -f event-types.json
sparrow events export --prefix order. > event-types.json
sparrow events export --all -f event-types.json
# preview, then import ("-f -" reads stdin)
sparrow events import -f event-types.json --dry-run
sparrow events import -f event-types.json

The import prints what each entry does (created, a new version v2→v3, updated, unchanged), the reasons a schema change is breaking, and each subscription whose template fails against the new schema. It writes nothing, and exits non-zero, until every block is acknowledged:

Flag Accepts
--accept-version-mismatch a bundle exported by a different Sparrow version or format
--accept-edited a bundle edited after it was exported
--allow-breaking schema changes that are breaking for existing subscriptions
--pause-affected also pause the subscriptions whose template fails

A dry run that would be blocked also exits non-zero, so a promotion job can run --dry-run as a check.

Lists registered webhooks (id, active state, health, URL) or, with an id argument, shows that webhook’s details plus its subscriptions.

Terminal window
sparrow webhooks # list all webhooks
sparrow webhooks --active # only active webhooks
sparrow webhooks <webhook-id> # one webhook's detail + subscriptions
sparrow webhooks -o json # machine-readable output

Polls the deliveries API every 2 seconds and prints each new row:

TIME EVENT STATUS CODE ATTEMPTS URL
2026-09-12 14:03:21 9f0c1a2b-... success 200 1/14 https://hooks.example/x

ATTEMPTS is attempts made out of the maximum: the first try plus the webhook’s max_retries (13 by default).

Terminal window
sparrow tail deliveries # follow everything in the consumer
sparrow tail deliveries --status failed # only failures
sparrow tail deliveries --once # print the current batch and exit (scripting/CI)
sparrow tail deliveries --limit 100 # fetch up to 100 rows per poll (default 50)

Ctrl-C exits cleanly.

Starts a local HTTP receiver, registers it as a temporary webhook, and pretty-prints every delivery (signature verified against the registration secret via the Standard Webhooks headers). The webhook is deleted on Ctrl-C.

Terminal window
sparrow listen --event order.created --event order.cancelled
sparrow listen --event order.created --port 9099
sparrow listen --event order.created --bind 127.0.0.1 # loopback only
sparrow listen --event order.created --forward http://localhost:3000/hooks # proxy to your app, mirror its status
sparrow listen --event order.created --public-url https://my-tunnel.example # e.g. an ngrok/cloudflared tunnel

Only deliveries signed with the temporary webhook’s secret are accepted; unsigned or mis-signed requests get 401 and are never forwarded with --forward. Request bodies are capped at 5 MiB.

--bind controls the listen address (default: all interfaces, so a Dockerized server can reach it). Use --bind 127.0.0.1 for loopback only.

Local-dev caveats:

  • Without --public-url, the webhook is registered as http://host.docker.internal:<port> — this assumes the Sparrow server runs in Docker on the same machine (Docker Desktop resolves host.docker.internal to your host; the local evaluation Compose file maps it on Linux too). If the server runs directly on the host, pass --public-url http://localhost:<port>.
  • Sparrow blocks private-network delivery URLs by default (SSRF guard). For local receivers, start the server with SPARROW_ALLOW_PRIVATE_NETWORKS=true (the local evaluation Compose file already sets this).

Lists the recipes you can apply: the built-in catalog plus local ./recipes/<name>.yaml and $SPARROW_RECIPES_DIR/<name>.yaml files (the SOURCE column says which; a local file overrides a built-in of the same name). Params marked * are required. Supports -o json|yaml.

Terminal window
sparrow recipes
sparrow recipes show pagerduty # or just: sparrow recipes pagerduty
sparrow recipes validate slack -e order.created
sparrow recipes validate --file ./recipes/teams.yaml --param webhook_url=https://example.com/x

sparrow recipes show <name> prints one recipe in full: each param with its help, example, default and docs link, the destination URL and headers, the transform template, the guidance, and the sparrow use line to apply it.

sparrow recipes validate <name>|--file <path> checks a recipe without applying it: the schema and param rules, the built-in catalog’s shipping rules (as warnings), and a strict render of the template with params substituted. The render uses --payload when given, else the registered sample payload of --event, else a built-in sample. It exits non-zero when the recipe has errors, so it works in CI for recipes you keep in a repo.

Applies a recipe: registers a webhook with the recipe’s URL and headers, then enables its transform template (plus any --label filters) on the created subscription(s). All shipped recipes are embedded in the binary, so sparrow use slack works anywhere. Lookup order: --file, then ./recipes/<name>.yaml, then $SPARROW_RECIPES_DIR/<name>.yaml (local files override a built-in of the same name), then the built-in catalog.

Terminal window
sparrow use slack --event order.created --param webhook_url=https://hooks.slack.com/services/T00/B00/xxx
sparrow use slack --event order.created --label env=prod \
--param webhook_url=https://hooks.slack.com/services/T00/B00/xxx # only prod-labelled events
sparrow use myrecipe --file ./my-recipe.yaml --event user.signup

Recipe params not passed with --param are prompted for when stdin is a terminal; anywhere else (a script, CI, </dev/null), every missing required param is named in one error. The {{param "x"}} tokens are substituted client-side before registration; the transform template itself is rendered server-side per delivery.

Before creating anything, use validates the recipe and renders its template against the first --event’s registered sample payload (a built-in sample if it has none). A template that can’t render creates nothing.

Flag What it does
--dry-run Validates and prints what would be created or changed, plus a sample delivery; changes nothing
--update Re-applies the recipe to the existing webhook for the same destination: the --event subscriptions get the recipe’s transform and labels (missing ones are created) and the webhook gets its headers. Subscriptions to other events are left alone
--label key=value Label filter on the subscriptions (repeatable)
-o json|yaml Prints the result as data: action, webhook and subscription ids, the rendered sample

A consumer has one webhook per URL, so applying a recipe to the same destination again is refused and names the existing webhook; re-run with --update to change it.

Terminal window
sparrow use pagerduty -e payment.failed --param routing_key=R0UT1NG --dry-run
sparrow use slack -e order.created -e order.refunded --update \
--param webhook_url=https://hooks.slack.com/services/T00/B00/xxx

Renders a transform template entirely locally — no network call — with the same Go template engine the server uses for deliveries, against a synthetic sample context (event_id: "evt_sample", attempt: 1, current timestamp, your --payload). It’s the debugging loop for recipe templates before you apply one:

Terminal window
sparrow template test slack.tmpl --event-name order.created --payload '{"order_id":"ord_1","amount":42}'
sparrow template test slack.tmpl --payload @sample-event.json

Prints the rendered output, or the parse/render error. Like a subscription, it treats a field the payload lacks as an error; pass --missing-key zero to render it as <no value> instead. The template context is {{.event_id}}, {{.event_name}}, {{.timestamp}}, {{.attempt}}, and {{.payload}}, with helper functions like json and upper (GET /v1/template-functions lists them all).

Start from a built-in recipe’s template, or write your own:

Terminal window
# copy the built-in Slack template into a file you can edit
sparrow recipes show slack -o json | jq -r .subscription.transform_template > slack.tmpl
# or write one from scratch
cat > partner.tmpl <<'EOF'
{{ dict "partner_id" "acme" "order" .payload.order_id "total" (div .payload.amount_cents 100) | json }}
EOF
# iterate until the output is what the destination expects
sparrow template test partner.tmpl --event-name order.completed \
--payload '{"order_id": "ord_9988", "amount_cents": 4995}'
# {"order":"ord_9988","partner_id":"acme","total":49.95}

Then put the template in a recipe file under subscription.transform_template (a YAML block scalar, |, keeps it verbatim) and declare the values that differ per install as params. The file name must match name:

partner.yaml
version: 1
name: partner
description: Order summary for Acme's partner API
params:
- name: endpoint
prompt: "Partner endpoint URL"
required: true
- name: api_token
prompt: "Partner API token"
required: true
secret: true
webhook:
requires_transform: true
url: '{{param "endpoint"}}'
headers: {Content-Type: application/json}
secret_headers:
Authorization: 'Bearer {{param "api_token"}}'
subscription:
transform_template: |
{{ dict "partner_id" "acme" "order" .payload.order_id "total" (div .payload.amount_cents 100) | json }}
Terminal window
sparrow use partner --file ./partner.yaml --event order.completed \
--param endpoint=https://partner.example.com/orders --param api_token=$PARTNER_TOKEN
# created webhook 0e37f464-... -> https://partner.example.com/orders
# created subscription a2edd100-... for order.completed, transform on
# recipe "partner" applied in consumer "default"
sparrow push order.completed -d '{"order_id": "ord_9988", "amount_cents": 4995}'
sparrow tail deliveries

Recipes → Writing your own lists every recipe field.

Manage access tokens – named, revocable credentials for people, CI, and services. A tenant-wide token (no --consumer) works exactly like SPARROW_API_KEY and expires after the server’s default (90 days unless SPARROW_TOKEN_DEFAULT_TTL changes it) unless --ttl is given; a consumer token only works through the portal API, limited to that consumer. To give a person access to the web UI, prefer sparrow invite (next section).

Terminal window
sparrow tokens create --name ci-deploy
sparrow tokens create --name acme-sync --consumer acme --ttl 30d
sparrow tokens create --name build-bot --ttl never
sparrow tokens create --name alice -o json

Prints the secret once. Store it now – it is not shown again. Send it as X-API-Key or Authorization: Bearer. Durations accept Go syntax plus a d suffix (e.g. 90d, 12h, 15m). Tenant-wide tokens default to the server’s SPARROW_TOKEN_DEFAULT_TTL (90 days unless changed); pass --ttl never for one that does not expire (revoke it when no longer needed). Consumer tokens default to 7 days (max 30) and always expire. sparrow invite --token-ttl takes the same values.

Terminal window
sparrow tokens list # active tokens
sparrow tokens list --all # include revoked and expired
sparrow tokens list -o json

Table columns: ID, NAME, ACCESS, CREATED BY, LAST USED, EXPIRES, STATUS.

Terminal window
sparrow tokens revoke <token-id>

The token stops working immediately on this server and within 30 seconds everywhere else. Revoking is permanent and idempotent.

Invite someone to the web UI (or a consumer’s portal) with a one-time link:

Terminal window
sparrow invite alice
sparrow invite "acme support" --consumer acme --ttl 7d
sparrow invite bob --ttl 15m --ui-url https://sparrow.example.com
sparrow invite carol --token-ttl 90d -o json

Opening the link creates a named access token for that browser, so nobody pastes a key into chat. The link works once, expires after --ttl (default 24 hours, max 7 days), and can be cancelled with sparrow invites cancel. With --consumer, the link opens that consumer’s portal instead of the operator console. --ui-url defaults to the server URL (right when the server serves the UI itself); pass the UI’s address when it is hosted separately.

List or cancel pending invites:

Terminal window
sparrow invites list # pending invites
sparrow invites list --all # include redeemed, cancelled, expired
sparrow invites cancel <invite-id>

Table columns: ID, FOR, ACCESS, INVITED BY, EXPIRES, STATUS.

Prints aggregate delivery statistics for the current consumer: total webhooks (active), delivery attempts (succeeded, failed), the attempt success rate, and the deliveries in flight now (pending, sending or retrying). The counts are attempts, not deliveries: a delivery that succeeded on its 3rd try adds one successful and two failed attempts.

Terminal window
sparrow stats
sparrow stats -o json

Lists the template functions available inside a transform_template, or shows one function’s full documentation. These are the helpers you can pipe values through in recipes and transforms (json, upper, ellipsis, dig, etc.).

Terminal window
sparrow functions # list all functions
sparrow functions json # show one function's docs
sparrow functions -o json # machine-readable output

Serves Sparrow to AI agents over the Model Context Protocol on stdio, so a coding agent can inspect webhooks, explain failed deliveries, and, with --allow-write, set up subscriptions and test them end to end against your real server.

Read-only tools (always on):

Tool What it does
list_webhooks The consumer’s webhooks with url, events, active flag and health
get_webhook One webhook with its subscriptions (event, label filters, transform template)
list_subscriptions One webhook’s subscriptions: event, label filters, transform template
list_deliveries Deliveries newest first, filterable by status, webhook_id and event_name, paged with cursor
get_delivery_attempts Per-attempt history of one delivery (code, timing, error category and message)
list_event_types Registered event types with schema and sample payload
get_event_type One event type with schema and sample payload; versions adds its version history
list_events Events pushed to the consumer, newest first, with payload, labels and delivery counts; filter by event, schema_valid and labels, paged with cursor
export_event_types Exports definitions as one bundle, like sparrow events export: exactly one of names, prefix or all
get_stats Delivery attempt counts by outcome, attempt success rate, deliveries in flight
test_template Renders a transform template server-side with the delivery engine, against payload when given (e.g. a real one from list_events), else the event type’s sample payload
list_recipes Recipes with their params: the built-in catalog plus local recipe files (source says which)
get_recipe One recipe in full (url, headers, template, guidance); local files override built-ins as in sparrow use
validate_recipe Checks a recipe by name or as draft YAML: schema and param rules, the catalog’s shipping rules as warnings, and a strict local render against payload, else event_name’s registered sample, else a built-in sample. Nothing is created

Write tools (--allow-write):

Tool What it does
push_event Pushes one event; an unknown event type is auto-created (a test push). A new name must follow the naming rules, like order.created, or the push gets a 400
retry_delivery Re-attempts one delivery immediately
update_event_type Sets an event type’s schema, description, metadata or active flag. A new schema creates a version and regenerates the sample payload test_template renders against. A breaking change to a subscribed type needs allow_breaking
import_event_types Imports a bundle, like sparrow events import. A dry run unless dry_run is false; the result names what would block it and the flag that accepts it (accept_version_mismatch, accept_edited, allow_breaking), and pause_affected pauses subscriptions whose template would fail
register_webhook Registers an endpoint, optionally subscribed to events in the same call
create_subscription Subscribes an existing webhook to an event, with optional filters and template. A template that does not parse is refused with the parse error
update_subscription Changes one subscription’s transform template or label filters, e.g. to fix a failing template. A template that does not parse is refused; the saved change is recorded in the template history
delete_subscription Deletes one subscription; the webhook stays
delete_webhook Deletes a webhook and its subscriptions
apply_recipe Applies a recipe by name or inline YAML, like sparrow use: validates first against the event’s registered sample and creates nothing if that fails. dry_run previews; update_existing re-applies to the existing webhook for the destination (without it, a second apply fails and names that webhook). Missing params are all named in one error
start_listen Starts a temporary local receiver behind a temp webhook, like sparrow listen
list_received Signature-verified deliveries the receiver has accepted so far
stop_listen Stops the receiver and deletes the temp webhook (also happens when the client disconnects)

Recipes follow the same pattern: an agent can start from get_recipe, write a new recipe as YAML, iterate with validate_recipe until it is valid and renders the body the destination expects, then apply_recipe the same YAML. Secret param values are masked in validation output.

The listen tools let an agent close the loop on its own: start_listen for order.created, push_event, list_received to see the signed envelope or the transformed body, stop_listen. The same SSRF note as sparrow listen applies: the server must allow private-network delivery URLs for a local receiver.

Every tool returns the REST API response (minus its $schema link), so the fields match the API reference. The server also sends the client instructions describing these workflows, so an agent knows where to start without being told.

Register it in your MCP client’s server config. Most clients use this shape:

{
"mcpServers": {
"sparrow": {
"command": "sparrow",
"args": ["mcp", "--url", "http://localhost:8080", "--consumer", "default"]
}
}
}

Add "--allow-write" to args to let the agent push, subscribe, apply recipes, set event type schemas, import event types and run a local receiver.

sparrow mcp has no key of its own. It is a stdio server: the MCP client starts it as a child process and talks to it over stdin/stdout, so it opens no port and only the client that launched it can call it. Each tool call is a REST request to Sparrow, and the server authenticates that request exactly as it does for any other sparrow command.

So the key the agent needs is the server’s: whatever --api-key, SPARROW_API_KEY or api_key in ~/.sparrow/config.yaml resolves to (Configuration), sent as X-API-Key. If the server has no SPARROW_API_KEY set, /v1 is open and the MCP server works without one, which is why a local make run setup needs no key.

Against a server that requires a key, give the agent its own access token rather than the master key, so you can see its use under LAST USED and revoke it on its own:

Terminal window
sparrow tokens create --name claude-mcp --ttl 30d
{
"mcpServers": {
"sparrow": {
"command": "sparrow",
"args": ["mcp", "--url", "https://sparrow.internal", "--consumer", "default"],
"env": { "SPARROW_API_KEY": "<token>" }
}
}
}

Use a tenant-wide token (no --consumer). Consumer tokens only work through the portal API, so every tool call made with one gets a 403. The token sets what the agent can reach; --allow-write only controls which tools it is offered. If an agent should never change anything, leave --allow-write off. The token still has full write access, so anyone who has it can make writes with other tools.

If ~/.sparrow/config.yaml already holds a key, sparrow mcp picks it up with no env entry. Set SPARROW_API_KEY in env anyway when the agent should use a different credential from the one you use in the terminal; the environment wins over the config file.

What to do in the UI, the CLI or the agent

Section titled “What to do in the UI, the CLI or the agent”

The MCP server covers the day-to-day loop: inspect, explain a failure, write and test a template, subscribe, push and watch. The web UI can do everything the API can, and a few things are only there. Use this table to pick the tool for the task; the last column is the recommendation.

Task UI CLI MCP Recommended
Inspect webhooks, subscriptions, deliveries and attempts Webhooks, Deliveries webhooks, tail deliveries list_*, get_* Agent, to explain a failure in context
Push a test event Push Test Event push push_event CLI or agent
Infer a schema from real events Events: Infer schema - list_events, then update_event_type UI, or the agent when it is about to write templates (see below)
Edit an event type’s schema, read its versions Events: Edit, Versions events, events versions (read) get_event_type, update_event_type UI for review, agent for a first schema
Move event types between environments Events: Export all, Import with preview events export, events import --dry-run export_event_types, import_event_types CLI in scripts and CI, UI or agent for a one-off
Write and test a transform template Template editor, live strict render template test test_template, validate_recipe Agent or UI
Draft a template with AI, or copy the prompt Template editor: AI drawer, Copy prompt - - UI; an agent writes the template itself
Go back to an earlier template Template editor: history - - UI
Connect a destination from a recipe Register webhook: Use recipe use apply_recipe Any; the agent validates first
Register a webhook, subscribe it Register webhook, subscription pages use register_webhook, create_subscription Any
Develop a receiver locally - listen --forward start_listen, list_received CLI for your app, agent for its own checks
Retry one delivery Delivery details - retry_delivery Agent or UI
Retry held or failed deliveries in bulk, re-push events Deliveries, event reports, held-deliveries notice - - UI: bulk jobs snapshot their targets and show progress
Pause or resume a webhook or subscription Webhook and subscription pages - - UI
Rotate a signing secret Webhook page - - UI: the new secret is shown once
Health dashboard and alert configs Health dashboard, webhook page stats (counts only) get_stats (counts only) UI
Tokens and invites Access tokens, invite, invites - UI or CLI; never through an agent

Anything marked - can still be done with the REST API.

Recommended workflows:

  • Test templates against real payloads, and give event types a schema. An event type created by a push has no schema and no sample payload, so test_template without a payload has nothing to render against and fails on the first field it reads. Pass a real event’s payload from list_events instead: that is also the closest preview of what a receiver gets. For a sample that every tool and the UI can use, push a few real events, then either use Infer schema on the Events page (Inferring a schema from real events) or let the agent do it: list_events for that type, a schema covering what the payloads share, update_event_type. The server generates the sample from the schema, so its values are placeholders except for enum values. The UI’s coverage table is the better review of an inferred schema: it shows which fields every event had.
  • Export event types to promote them. Once the schemas are right on a development instance, export them and import them into staging and production instead of re-pushing there (Exporting and importing event types). The import preview names every subscription whose template would fail against the new sample. An agent connected to each server can pass export_event_types output to import_event_types, which previews first.
  • Let the agent build, then review in the UI. An agent can draft a template with test_template, subscribe with create_subscription, and prove it with start_listen and push_event. Open the subscription in the UI afterwards: the template history shows each saved version, and loading an earlier one into the editor and saving it undoes a bad change.
  • Keep account and bulk actions in the UI. Bulk retries, re-pushes, pauses, secret rotation and access tokens have no MCP tools. They affect many deliveries or other people’s access, and the UI shows what will change before it happens.

Prints the CLI version (set at build time via -ldflags "-X main.version=...").

Worked example: develop a receiver on your laptop

Section titled “Worked example: develop a receiver on your laptop”

You’re building the endpoint that handles user.signup in an app running on http://localhost:3000, against a Sparrow server in Docker on the same machine.

Terminal window
sparrow listen --event user.signup --forward http://localhost:3000/api/webhooks
# listening on [::]:53021, registered webhook 6c1f... -> http://host.docker.internal:53021 (events: [user.signup])
# press Ctrl-C to stop and delete the webhook

In a second terminal, push a test event:

Terminal window
sparrow push user.signup -d '{"user_id": "u_1", "email": "ada@example.com"}'

The listen terminal prints the delivery (signature: verified), its headers and body, then forward: http://localhost:3000/api/webhooks -> 200. Your app’s status code goes back to Sparrow, so a 500 from your app shows up as a retrying delivery in sparrow tail deliveries, and you can watch the retries arrive. Ctrl-C deletes the temporary webhook.

listen checks signatures itself, with the temporary webhook’s secret, which it doesn’t print. If your app verifies signatures too, it rejects these forwarded requests. Skip verification in development, or register a webhook of your own to get a secret (Testing your receiver).