Running Deployments

prefector deployments run triggers one or more Prefect flow runs without waiting for them to complete (unless --watch is passed).

Trigger by name

prefector deployments run <deployment_name> --api-url "$PREFECT_API_URL"

Two name formats are accepted:

Bare name — matches any deployment with that name, regardless of which flow it belongs to. If multiple deployments share the name they are all triggered.

prefector deployments run my-deployment --api-url "$PREFECT_API_URL"

flow/deployment format — matches exactly one deployment. Returns an error if it is not found.

prefector deployments run my-flow/my-deployment --api-url "$PREFECT_API_URL"

Trigger by tag

--tag can be specified multiple times. Only deployments that have all of the specified tags are triggered (intersection, not union).

# Trigger all deployments tagged with both "nightly" and "prod"
prefector deployments run --tag nightly --tag prod --api-url "$PREFECT_API_URL"

# Trigger all deployments tagged "orchestrator"
prefector deployments run --tag orchestrator --api-url "$PREFECT_API_URL"

--tag and a positional deployment name are mutually exclusive.

Output

For each triggered run, Prefector prints a URL to view the run in the Prefect UI:

Triggering my-flow/my-deployment
✓ https://prefect.example.com/runs/flow-run/ec814d65-...

Watch mode

Pass --watch to poll all triggered runs and wait for them to reach a terminal state before the command exits.

prefector deployments run --tag orchestrator --watch --api-url "$PREFECT_API_URL"

When watching:

• All runs are triggered first, then polled together (not sequentially).
• Each run's final state is printed as it completes.
• If any run does not complete successfully, the command exits with a non-zero code after all runs have finished — not as soon as the first failure is detected.

Triggering my-flow/orchestrator-a
✓ https://prefect.example.com/runs/flow-run/abc123
Triggering my-flow/orchestrator-b
✓ https://prefect.example.com/runs/flow-run/def456
my-flow/orchestrator-a: Completed
my-flow/orchestrator-b: Failed
Error: Flow run(s) did not complete: my-flow/orchestrator-b

Options

Option	Description
deployment_name	Positional argument. Bare name or flow/deployment format.
--tag	Run all deployments with this tag. Repeatable; uses AND semantics.
--watch	Wait for all triggered runs to reach a terminal state.
--api-url	Prefect API URL (or set PREFECT_API_URL). See Authentication.