cli
Prefect CLI commands for mutations. The MCP server is read-only - use this skill when you need to trigger deployments, cancel flow runs, create automations, or modify Prefect resources.
When & Why to Use This Skill
This Claude skill enables seamless interaction with the Prefect CLI to perform critical mutations and resource management. It allows agents to trigger deployments, cancel flow runs, and manage automations, bridging the gap for active workflow orchestration and DevOps automation beyond read-only access.
Use Cases
- Triggering deployments: Execute specific Prefect deployments by name or UUID to initiate data pipelines or scheduled tasks.
- Incident management: Rapidly cancel or delete stalled or failed flow runs to maintain orchestration health and resource efficiency.
- Automation creation: Programmatically create reactive automations from JSON or YAML files to respond to system events like flow failures.
- Advanced resource modification: Use direct API access via the CLI to perform complex mutations and retrieve detailed JSON metadata for precise resource tracking.
| name | cli |
|---|---|
| description | Prefect CLI commands for mutations. The MCP server is read-only - use this skill when you need to trigger deployments, cancel flow runs, create automations, or modify Prefect resources. |
Prefect CLI
The MCP server is read-only. For mutations, use the CLI.
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.