cuitty-pilot provides both async (PilotClient) and synchronous (PilotClientSync) Python clients for the Pilot API. Built on httpx with dataclass types and context manager support.
sfw pip install cuitty-pilotRequires Python 3.10+ and httpx.
import asyncio\nfrom cuitty_pilot import PilotClient, StartRunRequest\n\nasync def main():\n async with PilotClient(\"http://localhost:4320\", auth_token=\"pk_...\") as client:\n # List all playbooks\n playbooks = await client.list_playbooks()\n\n # Start a run\n resp = await client.start_run(StartRunRequest(\n playbook_id=\"cloudflare.dns.add-a-record\",\n mode=\"autonomous\",\n inputs={\"zone\": \"example.com\", \"record_name\": \"app\", \"ip_address\": \"1.2.3.4\"},\n ))\n print(f\"Run started: {resp['id']} ({resp['status']})\")\n\n # Get run details\n run = await client.get_run(resp[\"id\"])\n print(f\"Steps: {len(run.steps)}\")\n\nasyncio.run(main())from cuitty_pilot import PilotClientSync, StartRunRequest\n\nwith PilotClientSync(\"http://localhost:4320\", auth_token=\"pk_...\") as client:\n playbooks = client.list_playbooks()\n resp = client.start_run(StartRunRequest(\n playbook_id=\"cloudflare.dns.add-a-record\",\n inputs={\"zone\": \"example.com\", \"record_name\": \"app\", \"ip_address\": \"1.2.3.4\"},\n ))\n run = client.get_run(resp[\"id\"])\n client.close()The primary client. Supports async with as a context manager.
client = PilotClient(\n base_url=\"http://localhost:4320\",\n auth_token=\"ey...\", # Optional bearer token\n timeout=30.0, # Per-request timeout in seconds (default 30.0)\n)| Method | Returns | Description |
|---|---|---|
health() | HealthStatus | Check server health |
list_playbooks(target?) | list[PlaybookSummary] | List playbooks, optionally filtered |
get_playbook(id) | Playbook | Get playbook by ID (latest version) |
create_playbook(req) | dict ({id, version, created}) | Create a new playbook |
update_playbook(id, req) | dict ({id, version}) | Update (version-bump) a playbook |
delete_playbook(id) | dict ({deleted}) | Delete all versions |
start_run(req) | dict ({id, status}) | Start a new run |
list_runs(status?, playbook_id?, limit?) | list[Run] | List runs with optional filters |
get_run(id) | Run | Get run details including steps |
abort_run(id) | dict ({aborted, runId}) | Abort a running or queued run |
approve_run(id, req) | dict ({approved, runId, stepId, decision}) | Submit approval decision |
list_providers() | list[Provider] | List all provider profiles |
close() | None | Close the underlying HTTP client |
Synchronous wrapper with an identical API. Supports with as a context manager.
client = PilotClientSync(\n base_url=\"http://localhost:4320\",\n auth_token=\"ey...\",\n timeout=30.0,\n)All methods are the same as PilotClient but without await.
# List all\nplaybooks = await client.list_playbooks()\n\n# Filter by target\ncf_playbooks = await client.list_playbooks(target=\"cloudflare\")\n\n# Get one\npb = await client.get_playbook(\"cloudflare.dns.add-a-record\")\nprint(pb.title, pb.document_yaml)\n\n# Create\nresp = await client.create_playbook(CreatePlaybookRequest(\n target=\"cloudflare\",\n title=\"Add CNAME record\",\n yaml=playbook_yaml,\n authored_by=\"human\",\n))\n\n# Update\nawait client.update_playbook(\"cloudflare.dns.add-cname\",\n UpdatePlaybookRequest(yaml=updated_yaml))\n\n# Delete\nawait client.delete_playbook(\"cloudflare.dns.add-cname\")# Start a run\nresp = await client.start_run(StartRunRequest(\n playbook_id=\"cloudflare.dns.add-a-record\",\n mode=\"interactive\",\n inputs={\"zone\": \"example.com\", \"record_name\": \"api\", \"ip_address\": \"1.2.3.4\"},\n provider_profile_id=\"cf-prod\",\n))\n\n# Get run with steps\nrun = await client.get_run(resp[\"id\"])\nfor step in run.steps:\n print(f\"{step.step_id}: {step.status} ({step.duration_ms}ms)\")\n\n# List runs with filters\nrunning = await client.list_runs(status=\"running\", limit=10)\n\n# Abort\nawait client.abort_run(run_id)\n\n# Approve a step\nawait client.approve_run(run_id, ApproveRequest(\n step_id=\"save\",\n decision=\"approve\",\n))All types are Python dataclass instances.
| Type | Fields |
|---|---|
Playbook | id, version, target, title, document_yaml, authored_by, created_at |
PlaybookSummary | id, version, target, title, authored_by |
Run | id, project_id, playbook_id, playbook_version, mode, status, inputs_json, outputs_json, provider_profile_id?, started_at?, completed_at?, failed_step_id?, error_message?, steps: list[RunStep] |
RunStep | id, run_id, step_id, action, status, selector_tried_json, ai_used, started_at?, completed_at?, duration_ms?, error_message? |
Provider | id, project_id, provider, label, base_url, last_authenticated?, expires_at? |
HealthStatus | status, database, driver_pool: dict, provider_sessions: dict, last_checked |
| Type | Fields |
|---|---|
StartRunRequest | playbook_id, mode=\"autonomous\", version?, inputs?: dict, provider_profile_id?, project_id? |
CreatePlaybookRequest | target, title, yaml, authored_by? |
UpdatePlaybookRequest | yaml, target?, title?, authored_by? |
ApproveRequest | step_id, decision=\"approve\" |
The SDK raises typed exceptions from a common PilotError base class:
from cuitty_pilot import PilotAPIError, PilotConnectionError\n\ntry:\n await client.start_run(StartRunRequest(playbook_id=\"nonexistent\"))\nexcept PilotAPIError as e:\n print(f\"API error {e.status}: {e.message}\")\nexcept PilotConnectionError as e:\n print(f\"Cannot reach Pilot: {e}\")\n if e.cause:\n print(f\"Underlying: {e.cause}\")| Exception | Properties | When |
|---|---|---|
PilotError | base class | All SDK errors |
PilotAPIError | status: int, message: str | Non-2xx HTTP response |
PilotConnectionError | message: str, cause: Exception | None | Network or timeout failure |