Home

Prefector

Prefector is a CLI for deploying Prefect blocks and deployments from downstream project specs. It provides a CI-first approach to managing Prefect resources as code, stored alongside flows and data pipelines.

What it does

Command group	What it manages
prefector blocks	Reads block field values from the environment or a secrets manager, then saves the configured block to Prefect
prefector deployments	Registers deployment specs with Prefect; resolves image names from a manifest; supports triggering runs by name or tag

Install

pip install prefector

Install with Keeper Secrets Manager support:

pip install "prefector[keeper]"

Prefector must be installed into the same Python environment as the block spec and flow modules it needs to import.

Quick reference

# Blocks
prefector blocks list --blocks-dir path/to/specs
prefector blocks deploy --blocks-dir path/to/specs --api-url "$PREFECT_API_URL"

# Deployments — register with Prefect
prefector deployments list --deployments-dir path/to/specs
prefector deployments deploy \
  --deployments-dir path/to/specs \
  --images-manifest path/to/images.yaml \
  --image-prefix ghcr.io/example \
  --api-url "$PREFECT_API_URL"

# Deployments — trigger runs
prefector deployments run my-flow/my-deployment --api-url "$PREFECT_API_URL"
prefector deployments run --tag nightly --tag prod --api-url "$PREFECT_API_URL"
prefector deployments run my-deployment --watch --api-url "$PREFECT_API_URL"

Pages

• Blocks — writing block spec modules and the optional block-sources.yaml
• Deployments — deployment YAML specs, images manifest, and registering with Prefect
• Running Deployments — triggering flow runs by name or tag with optional watch
• Authentication — connecting to self-hosted Prefect with basic auth or Keycloak

Global flags

--debug prints full tracebacks instead of the short user-friendly error message. Useful when diagnosing unexpected failures in CI.

prefector --debug blocks deploy ...