cli

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:

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

Avoiding Truncated Output

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

# Use `prefect api` for raw JSON (preferred for agents)
prefect api POST /flow_runs/filter --data '{"limit": 5}'

# Use inspect with -o json for single resources
prefect flow-run inspect <uuid> -o json
prefect deployment inspect <name> -o json

IDs Must Be Complete UUIDs

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

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

Common Mutations

Task	Command
Trigger deployment	prefect deployment run 'flow-name/deployment-name'
Trigger by ID	prefect deployment run --id <deployment-uuid>
Cancel flow run	prefect --no-prompt flow-run cancel <uuid>
Delete flow run	prefect --no-prompt flow-run delete <uuid>
Delete deployment	prefect --no-prompt deployment delete <name>

Direct API Access

prefect api gives full API access with JSON output:

# List flow runs (with filters)
prefect api POST /flow_runs/filter --data '{"limit": 10}'

# Filter by state
prefect api POST /flow_runs/filter --data '{"flow_runs": {"state": {"type": {"any_": ["FAILED"]}}}}'

# Delete a flow run
prefect api DELETE /flow_runs/<uuid>

# Cancel a flow run
prefect api POST /flow_runs/<uuid>/set_state --data '{"state": {"type": "CANCELLING"}}'

Automation Creation

Create from JSON string (inline):

prefect automation create --from-json '{
  "name": "notify-on-failure",
  "trigger": {
    "posture": "Reactive",
    "expect": ["prefect.flow-run.Failed"],
    "match": {"prefect.resource.id": "prefect.flow-run.*"}
  },
  "actions": [{"type": "send-notification", ...}]
}'

Or from file:

prefect 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()