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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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"}}'
```

## Aut