Quickstart

From your app
to your agent.

Deploy a Worker to your own Cloudflare account, connect the CLI, and keep your events in one local database. Install the CLI with one command, on macOS or Linux.

00 / DEPLOY

Put the Worker in your account.

One Worker, two Durable Object classes and an R2 bucket, deployed by slurp cloud init. You need a Cloudflare account (the Free plan is enough to start) and Node 20+. The dialog has the commands.

Self-host

Run Slurp in your own Cloudflare account.

Your Worker, Durable Objects and R2 bucket live in your account. Slurp does not host your events. The Free plan is enough to start.

  1. Open Cloudflare's deploy page. It copies this project's backend into your account and creates the R2 bucket and Durable Objects for you.
  2. When it asks for ADMIN_TOKEN, paste a long random value, for example from openssl rand -base64 32. Keep it, for example in a file called admin-token.txt: it controls your deployment.
  3. When it finishes, open your new Worker's address (Cloudflare shows it, and it looks like https://slurp.YOUR-SUBDOMAIN.workers.dev). The page there shows the exact command to connect the CLI:
Terminal
slurp connect https://slurp.YOUR-SUBDOMAIN.workers.dev \
  --token-stdin < admin-token.txt
slurp setup
slurp init --name "My app"
Open Cloudflare deploy page ↗
Cost and limits
01 / INSTALL & CONNECT

Make a home for your events.

Install the CLI with the shell command or npm. slurp cloud init deploys your Worker and connects this computer to it. Already have one? slurp connect <url> --token-stdin checks its admin token and remembers it. Setup finds DuckDB or offers to install it. Init creates or selects an app by name. Run slurp projects to list registered projects.

Terminal
curl -LsSf https://github.com/hitSlop/slurp/releases/latest/download/slurp-cli-installer.sh | sh
# or: npm install -g @hitslop/slurp
slurp cloud init
slurp setup
cd /path/to/your/app
slurp init --name "My app"

slurp init opens a private offline quickstart with your project’s SDK instructions. Rerun init to refresh that page.

02 / CAPTURE

Send your first event.

The SDK is private until published. For development, build it and install the local package into your application:

Terminal
pnpm install
pnpm --filter @slurp/sdk build
# In your application:
npm install /absolute/path/to/this/repository/packages/sdk-js

Replace the placeholders with values in your private project quickstart. Publishable keys are ingest-only.

JavaScript / Node
import { init, track, flush } from '@slurp/sdk';

init({
  endpoint: 'YOUR_INGEST_URL',
  sourceId: 'YOUR_SOURCE_ID',
  key: 'YOUR_PUBLISHABLE_KEY',
});

track('signed_up', { plan: 'pro' });
await flush(); // Node: flush before exiting

Test from your terminal.

Inside your app or a subfolder, Slurp uses the nearest project binding and its saved SDK key.

Your app folder
slurp send signed_up --user-id demo_alice --data '{"demo":true}'
slurp sync

Sending confirms durable acceptance. Events appear in slurp sync after your Worker next seals an archive, about every 10 minutes by default (earlier when a batch reaches 8 MB).

Send events over HTTP.

Any language can POST canonical events as newline-delimited JSON to /v1/events on your Worker. Use Authorization: Bearer YOUR_PUBLISHABLE_KEY and Content-Type: application/x-ndjson. Tool-specific webhook payloads need translation into this format.

One NDJSON record (end with a newline)
{"id":"YOUR_UNIQUE_EVENT_ID","type":"track","timestamp":"2026-11-05T12:00:00Z","event":"signed_up","data":{"plan":"pro"}}

A successful response means durable acceptance. Retrying the exact same bytes is safe: the Worker answers with Slurp-Duplicate: 1 and local import ignores repeated event IDs.

03 / SYNC

Bring the events home.

Terminal · your workspace
slurp init --backend YOUR_BACKEND --source YOUR_SOURCE_ID
slurp sync
slurp sql 'SELECT event, count(*) AS n FROM events GROUP BY event'

Run slurp sync to download new archives from your Worker into your local DuckDB database. Recently accepted events may still be waiting for the next seal. Close open DuckDB sessions before syncing.

04 / AGENT

Give your agent the context.

Install the skill bundle
slurp agent setup --out .agents/skills/slurp --all

Ask your local coding agent to inspect the workspace and query its events. For a bot running on another machine, create a separate revocable read key:

Create bot access
slurp --backend YOUR_BACKEND source key create YOUR_SOURCE_ID --scope secret --name grok

Transfer the returned key through the bot’s secret store as SLURP_TOKEN, then run these steps on its machine:

Bot machine
slurp agent setup --out .agents/skills/slurp
# Put the bot read key in its secret store as SLURP_TOKEN.
slurp init --backend YOUR_BACKEND --source YOUR_SOURCE_ID
slurp sync

Keep keys out of URLs, reports, and skill files. Revoke a key with slurp source key revoke.

05 / REPORT

Keep the query with the finding.

Ask your agent to create report.md using the repository’s examples/events.md as a reference. Reports combine Markdown, named SQL queries, and metric, table, or chart blocks.

Validate, build, open
slurp report check report.md
slurp report build report.md --out ./report --png --pdf
slurp report open ./report

HTML embeds charts and fonts. PNG and PDF are ready to share. Review the included data before sharing a report.