Prefect CLI

The MCP server is read-only. For mutations, use the CLI.

Prefer MCP tools for reads (e.g., get_flow_runs, get_deployments). They return structured JSON with full UUIDs. Use prefect api only if MCP doesn't expose what you need.

Critical: Agent-Friendly Usage

The CLI is designed for interactive terminal use. For non-interactive (agent) use:

bash
1# ALWAYS use --no-prompt as a TOP-LEVEL flag to disable confirmations
2prefect --no-prompt flow-run delete <uuid>
3prefect --no-prompt deployment delete <name>

Avoiding Truncated Output

Rich table output truncates IDs and names, making them useless. Solutions:

bash
1# Use `prefect api` for raw JSON (preferred for agents)
2prefect api POST /flow_runs/filter --data '{"limit": 5}'
3
4# Use inspect with -o json for single resources
5prefect flow-run inspect <uuid> -o json
6prefect deployment inspect <name> -o json

IDs Must Be Complete UUIDs

Partial IDs don't work. Always get full UUIDs from JSON output:

bash
1# Get full flow run ID
2prefect api POST /flow_runs/filter --data '{"limit": 1}' | jq -r '.[0].id'

Common Mutations

Direct API Access

prefect api gives full API access with JSON output:

bash
1# List flow runs (with filters)
2prefect api POST /flow_runs/filter --data '{"limit": 10}'
3
4# Filter by state
5prefect api POST /flow_runs/filter --data '{"flow_runs": {"state": {"type": {"any_": ["FAILED"]}}}}'
6
7# Delete a flow run
8prefect api DELETE /flow_runs/<uuid>
9
10# Cancel a flow run
11prefect api POST /flow_runs/<uuid>/set_state --data '{"state": {"type": "CANCELLING"}}'

Automation Creation

Create from JSON string (inline):

bash
1prefect automation create --from-json '{
2  "name": "notify-on-failure",
3  "trigger": {
4    "posture": "Reactive",
5    "expect": ["prefect.flow-run.Failed"],
6    "match": {"prefect.resource.id": "prefect.flow-run.*"}
7  },
8  "actions": [{"type": "send-notification", ...}]
9}'

Or from file:

bash
1prefect automation create --from-file automation.yaml

Use get_automations() from the MCP server to inspect existing automation schemas.

Efficient Inspection

The get_flow_runs tool returns summarized data to save tokens:

• It omits full deployment and work pool schemas.
• If you see a "Late" run or need concurrency details, follow up with:
  • get_work_pools(filter={"name": ...})
  • get_deployments(filter={"id": ...})
  • get_dashboard()