Module commands 

Subcommand implementations. Each module owns its run(...) entry point and stays free of clap so the integration tests can drive it directly.

Modules

backfill

faucet backfill — replay a bounded historical window of a pipeline (#282): plan window units, run them with bounded parallelism, record durable progress, and report the per-unit outcome.

catalogcatalog

faucet catalog — browse the Data Movement Catalog (#279) accumulated by a config’s catalog: store: datasets, schema timelines, volume/freshness, and the lineage graph. Read-only; the same store faucet run / schedule / replicate write into (point faucet serve --history at the same URL to browse it in the control plane / web console instead).

completions

faucet completions <shell> — emit a static shell-completion script — plus the dynamic (runtime) candidate providers used by clap_complete’s CompleteEnv hook (#383).

conformance

faucet conformance — score connectors against the faucet SDK contract and report a maturity tier + capabilities (#330).

contractcontract

faucet contract — validate a config’s contract: block and print a human summary, or export it in a machine-readable format (--export contract | json-schema | openlineage). Offline-safe: secrets are never fetched (a contract holds no credentials).

devcli-dev

faucet dev — a watch-and-diff authoring loop (#283, cli-dev feature).

discover

faucet discover — connect to a config’s source, enumerate the datasets living behind it (tables / collections / indices / prefixes), and emit a ready-to-run config with one matrix row per dataset (#211).

dlq

faucet dlq — inspect / replay / discard dead-letter-queue envelopes.

doctor

faucet doctor — preflight probes for every connector in a config (#126).

explain

faucet explain — plain-English narration of what a pipeline does (#389).

fmt

faucet fmt — canonicalize a pipeline config (#387).

historycatalog

faucet history — terminal view of the run history recorded in a config’s catalog: store (#391).

init

faucet init — scaffold a starter pipeline.yaml from each connector’s JSON Schema. Defaults to a rest → jsonl pipeline so faucet init with no flags continues to produce the same shape it did before this command grew schema-driven scaffolding.

install

faucet install — tell the user how to obtain/enable a connector (#208).

list

faucet list — show every compiled-in source, sink, transform, and state-store backend so users can discover what their binary supports. --available instead lists every connector in the registry index (#208), marking which are compiled into this binary.

maskingmasking

faucet masking — validate a config’s masking: block and print which rules apply to each destination sink (the destination-scoping check). Offline-safe: secrets are never fetched (compiling a policy needs no credentials, and the key is not required to list rules).

mcpmcp

faucet mcp — an MCP server over stdio (issue #420).

migrate

faucet migrate — upgrade a config written against an older faucet grammar to the current shape (#388).

new

faucet new connector — scaffold a ready-to-build connector crate (#209).

notifynotify

faucet notify test — fire one synthetic event through a config’s notifications: rules to validate channel setup end-to-end (no pipeline runs). Uses the real delivery path, so a Slack/PagerDuty/webhook that is reachable will actually receive the test message.

plan

faucet plan — a read-only “what would this config do” preview (#283).

preview

faucet preview — run only the source side of the first root row and emit the first N records to stdout as JSON Lines.

replicate

faucet replicate — load a config with a replication: block, validate it, and run the two-phase snapshot→CDC orchestration.

run

faucet run — load a pipeline config, expand the matrix, execute every invocation under bounded concurrency.

scheduleschedule

faucet schedule — run a pipeline on a cron schedule in one long-running process. Reuses expand + executor::run_expanded per tick; keeps no state of its own (resumability rides the pipeline’s per-page bookmark). See docs/superpowers/specs/2026-05-30-faucet-schedule-design.md.

schema

faucet schema — print the JSON Schema for a connector’s config.

search

faucet search — find connectors in the registry index (#208).

serveserve

faucet serve — thin command layer: parse args into a ServeConfig, load the startup .env, and hand off to serve::run_server.

test

faucet test — run fixture-based offline pipeline tests (#210).

validate

faucet validate — parse + expand a pipeline config without running.

Functions

report

Render any CliError to a single line on stderr, scrubbing any resolved secret values that may have reached the error chain.