Installation

The faucet CLI

Prebuilt binaries (no Rust required)

Every faucet-cli release ships prebuilt binaries for macOS (Apple Silicon + Intel) and Linux (x86_64 + aarch64), so you don’t need a Rust toolchain to try it.

Homebrew (macOS / Linux):

brew install faucet-hq/faucet-stream/faucet-cli

(The formula is named after the faucet-cli package; it installs the faucet binary.)

Shell installer (macOS / Linux):

curl -LsSf https://github.com/faucet-hq/faucet-stream/releases/latest/download/faucet-cli-installer.sh | sh

Direct download: grab the archive for your platform from the latest faucet-cli GitHub Release (e.g. faucet-cli-aarch64-apple-darwin.tar.xz), verify it against the published .sha256 checksum, and put faucet on your PATH.

Verify provenance. The checksum is published next to the archive, so it only catches a corrupt download. To check that an archive (or the shell installer) was built by this repository’s release workflow, verify its build provenance attestation with the GitHub CLI:

gh attestation verify faucet-cli-aarch64-apple-darwin.tar.xz --repo faucet-hq/faucet-stream

Each release asset also has its attestation attached beside it as <asset>.sigstore.json, so the check works offline or from a mirror:

gh attestation verify faucet-cli-aarch64-apple-darwin.tar.xz \
  --bundle faucet-cli-aarch64-apple-darwin.tar.xz.sigstore.json \
  --repo faucet-hq/faucet-stream

Every release also carries SLSA level 3 provenance for all of its assets, faucet-cli.intoto.jsonl, which slsa-verifier checks:

slsa-verifier verify-artifact faucet-cli-aarch64-apple-darwin.tar.xz \
  --provenance-path faucet-cli.intoto.jsonl \
  --source-uri github.com/faucet-hq/faucet-stream \
  --source-tag faucet-cli-vX.Y.Z

Dependency inventory. The binaries are built with cargo-auditable, so each one carries its exact dependency list: cargo audit bin faucet checks an installed binary against the RustSec advisory database. Every release also attaches a CycloneDX SBOM of the shipped build, faucet-cli.cdx.json.

Container images on GHCR carry provenance and an SBOM, and are signed with Sigstore keyless signing:

gh attestation verify oci://ghcr.io/faucet-hq/faucet-stream:full --repo faucet-hq/faucet-stream
cosign verify ghcr.io/faucet-hq/faucet-stream:full \
  --certificate-identity-regexp '^https://github.com/faucet-hq/faucet-stream/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The prebuilt binary includes every feature: it is the CLI’s full build, the same set as the :latest / -full container image. That is every first-party connector, serve with the web console and its SQLite / Postgres history, schedule, triggers (webhook, object-arrival, Redis and Kafka watchers), templates and template sync, mcp, notify, secrets (${vault:…}, ${aws-sm:…}, ${gcp-sm:…}, ${azure-kv:…}), catalog, lineage, otel, tenants, encryption, and the sql / wasm transforms. The Oracle connectors are included too; using them needs Oracle Instant Client installed (see Oracle Instant Client) — every other connector runs without it.

Container images

Every faucet-cli release publishes these images to ghcr.io/faucet-hq/faucet-stream (tags :<profile> and :<version>-<profile>; :latest and :<version> are full). The floating :<profile> and :latest tags only ever point at the newest release; pin :<version>-<profile> for reproducible deploys. Each tag is a multi-arch image for linux/amd64 and linux/arm64 (Graviton, Ampere, Apple-silicon Docker), so the same tag runs on either kind of node; releases up to 1.14.0 were linux/amd64 only.

Tag	What is compiled in
full	The CLI’s full feature: every connector and every feature — serve with the web console, tenants, templates and template sync, triggers (all watchers), the SQL and WASM transforms, OTLP export, secret-manager references, encryption, every file format, lineage, the catalog, MCP — plus the Oracle Instant Client the Oracle connectors load at run time.
core	rest, postgres, s3, csv → postgres, s3, jsonl, stdout.
analytics	rest, postgres, s3, bigquery, snowflake → bigquery, snowflake, s3, jsonl.
cdc	postgres-cdc, mysql-cdc, mongodb-cdc → postgres, kafka, s3.

The lean profiles also carry serve, the console, templates, triggers (webhook), the catalog and the run-history backends. Each image’s size is recorded in the summary of the release’s Docker images workflow run. (1.13.3 alone also has a full-oracle tag, from when the Oracle client was a separate image; from the next release full carries it.) To build your own connector set, see deploy/README.md.

Pinning a version

To make a project use one faucet version everywhere (laptops, CI, production), pin it in the project’s mise.toml and use the same image tag in deployments; faucet init writes the pin. See Pinning the faucet version. Coding agents get faucet’s agent skills, which follow that pin.

Windows

Windows is not a supported platform yet: there is no prebuilt Windows binary, and faucet is run on macOS or Linux (including Linux containers on Kubernetes). Building from source on Windows is possible; if you do, expect these platform differences:

• Kafka: PLAIN, SCRAM-SHA-256/512, OAUTHBEARER and TLS work. Kerberos (sasl.mechanism: GSSAPI set through extra_client_config) is not available — it needs Cyrus SASL, which does not build on Windows.
• Stopping long-running verbs: faucet serve, schedule, mirror and backfill drain gracefully on Ctrl-C, Ctrl-Break, closing the console window, or a system shutdown (the Unix builds use SIGTERM). faucet schedule’s SIGHUP hot reload is Unix-only; restart the scheduler to pick up a changed config.
• Singer taps / targets: the child process gets the same grace period to exit, but Windows has no SIGTERM, so a tap that is still running when the grace period ends is terminated. The temporary config/state files are created in your per-user temp directory rather than with Unix 0600 mode.
• Paths: write Windows paths as plain YAML scalars (path: C:\data\in.csv) or with forward slashes; inside double quotes a backslash starts an escape. State-store keys are percent-encoded on disk, so :: in a key is safe.
• Template Hub cache: remote hubs are cached under %LOCALAPPDATA%\faucet\hub (override with FAUCET_HUB_CACHE).

macOS Gatekeeper

the binaries are not currently notarized. If macOS blocks the downloaded binary, clear the quarantine attribute: xattr -d com.apple.quarantine $(which faucet). Homebrew installs are not affected.

From source (crates.io)

For the full feature set, or any custom combination, install from crates.io:

cargo install faucet-cli                     # the default feature set
cargo install faucet-cli --features full     # everything (DuckDB, otel, triggers, …)

This gives you a faucet binary with every first-party connector compiled in except the three Oracle connectors, which are opt-in because they load Oracle Instant Client at runtime: cargo install faucet-cli --features "source-oracle,source-oracle-cdc,sink-oracle" (they are also part of full).

Choose your build (feature flags)

Every connector and runtime capability is a Cargo feature, so you can build exactly the binary you need. Connector features are named source-<name> and sink-<name>.

Bare minimum — the smallest useful binary (REST in, JSON Lines out):

cargo install faucet-cli --no-default-features --features "source-rest,sink-file"

Add a source or sink — list the connectors you want (plus transforms if you need in-flight shaping):

cargo install faucet-cli --no-default-features \
  --features "source-postgres,sink-bigquery,transforms"

Add a runtime capability — compose any of serve, serve-ui, schedule, lineage, transform-sql (embedded DuckDB), triggers, templates, catalog, otel, compression, quality, contract, masking:

cargo install faucet-cli --features "serve,schedule,transform-sql,lineage"

Run faucet list to see which sources, sinks, and transforms are compiled into your binary, and the connector catalog for every feature name.

The library

To embed pipelines in your own Rust program, depend on the umbrella crate and enable the connectors you need:

[dependencies]
# Default features include the REST source only.
faucet-stream = "1.0"

# Or enable specific connectors:
faucet-stream = { version = "1.0", features = ["source-rest", "sink-postgres", "sink-s3"] }

# Or everything:
faucet-stream = { version = "1.0", features = ["full"] }

Feature groups: source (all sources), sink (all sinks), state (all state-store backends), full (everything), and compression (gzip/zstd on the file-shaped connectors you’ve enabled).

You can also depend on individual connector crates directly (faucet-source-rest, faucet-sink-bigquery, …) — each depends only on faucet-core.

Requirements

• A recent stable Rust toolchain (see the repo’s rust-toolchain.toml for the current MSRV).
• Some connectors link native libraries — the Kafka connectors build librdkafka and need cmake and a C toolchain available at compile time.
• Building from source on Windows needs the MSVC build tools, CMake, Strawberry Perl and NASM on PATH (the vendored OpenSSL and aws-lc assemble with it).

Oracle Instant Client

The Oracle connectors (source-oracle, source-oracle-cdc, sink-oracle) are built on the oracle crate (ODPI-C), which compiles without any Oracle software but loads Oracle Instant Client at runtime. Install the Basic or Basic Light package from https://www.oracle.com/database/technologies/instant-client.html and put its directory on the library path:

# Linux (x86_64). Instant Client needs libaio (libaio1t64 on Ubuntu 24.04).
sudo apt-get install -y libaio1t64 || sudo apt-get install -y libaio1
unzip instantclient-basiclite-linuxx64.zip -d /opt/oracle
export LD_LIBRARY_PATH=/opt/oracle/instantclient_23_7:$LD_LIBRARY_PATH   # your version's directory

In a container, the full image ships the client.

On macOS put the directory on DYLD_LIBRARY_PATH (or symlink libclntsh.dylib into ~/lib); on Windows add it to PATH. Without the client an Oracle connector fails at connect time — including faucet doctor’s probe — with a DPI-1047 error and a hint naming this fix.

Next: run your first pipeline.