CLI

siphon validate / lint / diff / test / run / prune / import-airbyte — the engine, offline or live, from your terminal.

The siphon CLI runs the same engine the durable worker runs. It's the fastest way to author and verify a connector before it ever touches the control plane.

`siphon validate <file>`

Schema + semantic validation of a spec (YAML or JSON). Reports issues with a path.

pnpm siphon validate examples/github.yaml

Best-practice checks beyond schema validity — the things a valid spec can still get wrong: an incremental sync with no updatedAtPath (the watermark can't advance), client-hash detection with no hashFields, page/offset pagination with no stopWhen, a transform that never sets externalId, enrich.onError: fail_run, and a resource with no typed output.fields. Exits non-zero on warnings, so CI catches them.

pnpm siphon lint examples/trexo-crm.yaml

`siphon diff <a> <b>`

Structural diff of two specs (or two versions) — ~ changed, + added, - removed. Add --exit-code to fail when they differ (handy in CI / pre-publish checks).

pnpm siphon diff old.yaml new.yaml

`siphon test <file>`

Runs the spec's offline fixture tests — recorded responses plus an expected transform output — proving the mapping with zero network calls.

pnpm siphon test examples/github.yaml

`siphon run <file>`

Executes one resource end to end: auth → fetch → change-filter → enrich → transform → validate → deliver.

pnpm siphon run examples/offline/spec.yaml \
  --connection examples/offline/connection.json \
  --resource deals \
  --fixtures examples/offline/fixtures.json \
  --json

Flag	Purpose
`--connection <file>`	Supplies params, secrets, and egress policy.
`--resource <key>`	Run a single resource (default: all).
`--fixtures <file>`	Offline mode — replay recorded responses. Drop it to hit the real network.
`--json`	Machine-readable output.

`siphon prune --older-than <days>`

Delete old runs and webhook deliveries (retention). Needs DATABASE_URL.

pnpm siphon prune --older-than 30d --json

`siphon import-airbyte <manifest.yaml>`

Convert an Airbyte low-code manifest.yaml into a draft Siphon connector spec. Resolves the manifest's $ref pointers and $parameters interpolation, maps streams → resources (path, record selector → recordsPath, primary key → idPath, paginator → pagination strategy) and the authenticator → a Siphon auth strategy, rewriting {{ config['x'] }} → {{ secrets.x }}.

pnpm siphon import-airbyte path/to/source-stripe/manifest.yaml > examples/connectors/stripe.yaml

The output is a starting point, not a finished connector — it prints the spec to stdout and a list of things to review (auth secrets, per-resource paths, and the canonical field mapping) on stderr. Always siphon lint it and live-test with real credentials before publishing. This is the machinery behind the 76 draft specs in the connector catalog.

Because the engine is composed from injectable seams, siphon run --fixtures exercises the entire pipeline deterministically — the same code the worker runs in production.