Quickstart

The fastest way to feel how Siphon works is the CLI. It runs the same engine the durable worker runs — offline against fixtures, or against the real network.

Install

pnpm install

Validate a spec

Validation is schema + semantic (a spec's enrichment calls must form an acyclic DAG, watermark fields must exist for incremental modes, and so on). Errors point at a path.

pnpm siphon validate examples/github.yaml

Run the offline fixture tests

A spec can carry tests — fixtures plus an expected transform output — so you can prove the mapping is correct with zero network calls.

pnpm siphon test examples/github.yaml

Run a resource end to end

siphon run executes one resource through the full pipeline: auth → fetch → change-filter → enrich → transform → validate → deliver. Point it at fixtures for an offline dry run, or drop --fixtures to hit the real API using the connection's params and secrets.

# Offline — deterministic, from recorded fixtures
pnpm siphon run examples/offline/spec.yaml \
  --connection examples/offline/connection.json \
  --fixtures examples/offline/fixtures.json

# Real network — the connection supplies params/secrets/egress
pnpm siphon run examples/offline/spec.yaml \
  --connection examples/offline/connection.json

Add --resource <key> to run a single resource, or --json for machine-readable output.

Type-check and test everything

pnpm typecheck
pnpm test

Next steps