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.
Install
Section titled “Install”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):
curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh | shsparrow versionUpdating 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:
curl -fsSL https://raw.githubusercontent.com/sarathsp06/sparrow/main/scripts/install.sh | sh -s -- -v v1.0.0 -b ~/binSPARROW_VERSION=v1.0.0 SPARROW_INSTALL_DIR=~/bin sh install.sh # same thingsh install.sh -c server # the server binary (sparrow-server) instead of the CLIsh install.sh -f # reinstall the current versionPrebuilt 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:
# e.g. macOS arm64: sparrow-cli-<version>-darwin-arm64.tar.gztar xzf sparrow-cli-*.tar.gzsudo mv sparrow /usr/local/bin/Have a Go toolchain? Install straight from source instead:
go install github.com/sarathsp06/sparrow/satellites/sparrow@latest90-second quickstart
Section titled “90-second quickstart”# 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-Csparrow 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.
How it’s connected
Section titled “How it’s connected”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 status4. 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.
Configuration
Section titled “Configuration”sparrow init writes ~/.sparrow/config.yaml (mode 0600):
server_url: http://localhost:8080api_key: "" # sent as X-API-Key when setconsumer: defaultEvery 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.
Commands
Section titled “Commands”sparrow init
Section titled “sparrow init”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.
sparrow init --url https://sparrow.example.com --api-key $KEY --consumer paymentssparrow push <event-name>
Section titled “sparrow push <event-name>”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.
sparrow push order.created -d '{"order_id":"ord_1"}' # inline JSONsparrow push order.created -d @payload.json # from a filesparrow push order.created -l env=prod -l region=eu # labels for label_filterssparrow push order.created --idempotency-key ord_1-created # dedup: same key returns the original event idsparrow events
Section titled “sparrow events”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.
sparrow events # every event typesparrow events --active # only active event typessparrow events order.created # one type's detailsparrow events versions order.createdsparrow events -o json # machine-readable outputsparrow 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.
# export by name, by prefix, or everything (stdout by default)sparrow events export order.created order.shipped -f event-types.jsonsparrow events export --prefix order. > event-types.jsonsparrow events export --all -f event-types.json
# preview, then import ("-f -" reads stdin)sparrow events import -f event-types.json --dry-runsparrow events import -f event-types.jsonThe 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.
sparrow webhooks [id]
Section titled “sparrow webhooks [id]”Lists registered webhooks (id, active state, health, URL) or, with an id argument, shows that webhook’s details plus its subscriptions.
sparrow webhooks # list all webhookssparrow webhooks --active # only active webhookssparrow webhooks <webhook-id> # one webhook's detail + subscriptionssparrow webhooks -o json # machine-readable outputsparrow tail deliveries
Section titled “sparrow tail deliveries”Polls the deliveries API every 2 seconds and prints each new row:
TIME EVENT STATUS CODE ATTEMPTS URL2026-09-12 14:03:21 9f0c1a2b-... success 200 1/14 https://hooks.example/xATTEMPTS is attempts made out of the maximum: the first try plus the
webhook’s max_retries (13 by default).
sparrow tail deliveries # follow everything in the consumersparrow tail deliveries --status failed # only failuressparrow 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.
sparrow listen
Section titled “sparrow listen”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.
sparrow listen --event order.created --event order.cancelledsparrow listen --event order.created --port 9099sparrow listen --event order.created --bind 127.0.0.1 # loopback onlysparrow listen --event order.created --forward http://localhost:3000/hooks # proxy to your app, mirror its statussparrow listen --event order.created --public-url https://my-tunnel.example # e.g. an ngrok/cloudflared tunnelOnly 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 ashttp://host.docker.internal:<port>— this assumes the Sparrow server runs in Docker on the same machine (Docker Desktop resolveshost.docker.internalto 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).
sparrow recipes
Section titled “sparrow recipes”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.
sparrow recipessparrow recipes show pagerduty # or just: sparrow recipes pagerdutysparrow recipes validate slack -e order.createdsparrow recipes validate --file ./recipes/teams.yaml --param webhook_url=https://example.com/xsparrow 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.
sparrow use <recipe>
Section titled “sparrow use <recipe>”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.
sparrow use slack --event order.created --param webhook_url=https://hooks.slack.com/services/T00/B00/xxxsparrow use slack --event order.created --label env=prod \ --param webhook_url=https://hooks.slack.com/services/T00/B00/xxx # only prod-labelled eventssparrow use myrecipe --file ./my-recipe.yaml --event user.signupRecipe 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.
sparrow use pagerduty -e payment.failed --param routing_key=R0UT1NG --dry-runsparrow use slack -e order.created -e order.refunded --update \ --param webhook_url=https://hooks.slack.com/services/T00/B00/xxxsparrow template test <file>
Section titled “sparrow template test <file>”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:
sparrow template test slack.tmpl --event-name order.created --payload '{"order_id":"ord_1","amount":42}'sparrow template test slack.tmpl --payload @sample-event.jsonPrints 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).
From a template to a recipe
Section titled “From a template to a recipe”Start from a built-in recipe’s template, or write your own:
# copy the built-in Slack template into a file you can editsparrow recipes show slack -o json | jq -r .subscription.transform_template > slack.tmpl
# or write one from scratchcat > 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 expectssparrow 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:
version: 1name: partnerdescription: Order summary for Acme's partner APIparams: - name: endpoint prompt: "Partner endpoint URL" required: true - name: api_token prompt: "Partner API token" required: true secret: truewebhook: 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 }}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 deliveriesRecipes → Writing your own lists every recipe field.
sparrow tokens
Section titled “sparrow tokens”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).
sparrow tokens create
Section titled “sparrow tokens create”sparrow tokens create --name ci-deploysparrow tokens create --name acme-sync --consumer acme --ttl 30dsparrow tokens create --name build-bot --ttl neversparrow tokens create --name alice -o jsonPrints 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.
sparrow tokens list
Section titled “sparrow tokens list”sparrow tokens list # active tokenssparrow tokens list --all # include revoked and expiredsparrow tokens list -o jsonTable columns: ID, NAME, ACCESS, CREATED BY, LAST USED, EXPIRES, STATUS.
sparrow tokens revoke
Section titled “sparrow tokens revoke”sparrow tokens revoke <token-id>The token stops working immediately on this server and within 30 seconds everywhere else. Revoking is permanent and idempotent.
sparrow invite
Section titled “sparrow invite”Invite someone to the web UI (or a consumer’s portal) with a one-time link:
sparrow invite alicesparrow invite "acme support" --consumer acme --ttl 7dsparrow invite bob --ttl 15m --ui-url https://sparrow.example.comsparrow invite carol --token-ttl 90d -o jsonOpening 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.
sparrow invites
Section titled “sparrow invites”List or cancel pending invites:
sparrow invites list # pending invitessparrow invites list --all # include redeemed, cancelled, expiredsparrow invites cancel <invite-id>Table columns: ID, FOR, ACCESS, INVITED BY, EXPIRES, STATUS.
sparrow stats
Section titled “sparrow stats”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.
sparrow statssparrow stats -o jsonsparrow functions [name]
Section titled “sparrow functions [name]”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.).
sparrow functions # list all functionssparrow functions json # show one function's docssparrow functions -o json # machine-readable outputsparrow mcp
Section titled “sparrow mcp”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.
Authentication
Section titled “Authentication”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:
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_templatewithout apayloadhas nothing to render against and fails on the first field it reads. Pass a real event’s payload fromlist_eventsinstead: 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_eventsfor 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 forenumvalues. 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_typesoutput toimport_event_types, which previews first. - Let the agent build, then review in the UI. An agent can draft a
template with
test_template, subscribe withcreate_subscription, and prove it withstart_listenandpush_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.
sparrow version
Section titled “sparrow version”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.
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 webhookIn a second terminal, push a test event:
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).