{
  "slug": "pilot/sdk/react",
  "title": "Pilot React SDK",
  "description": "React hooks and components for Cuitty Pilot — manage playbooks, runs, and real-time events in React apps.",
  "url": "https://cuitty.com/docs/pilot/sdk/react",
  "markdown_url": "https://cuitty.com/docs/pilot/sdk/react.md",
  "json_url": "https://cuitty.com/docs/pilot/sdk/react.json",
  "frontmatter": {
    "title": "Pilot React SDK",
    "description": "React hooks and components for Cuitty Pilot — manage playbooks, runs, and real-time events in React apps.",
    "order": 12,
    "section": "Pilot",
    "updatedAt": "2026-06-01"
  },
  "headings": [
    {
      "depth": 1,
      "slug": "pilot-react-sdk",
      "text": "Pilot React SDK"
    },
    {
      "depth": 2,
      "slug": "install",
      "text": "Install"
    },
    {
      "depth": 2,
      "slug": "quick-start",
      "text": "Quick start"
    },
    {
      "depth": 2,
      "slug": "pilotprovider",
      "text": "PilotProvider"
    },
    {
      "depth": 3,
      "slug": "usepilot",
      "text": "usePilot()"
    },
    {
      "depth": 2,
      "slug": "hooks",
      "text": "Hooks"
    },
    {
      "depth": 3,
      "slug": "useplaybooksoptions",
      "text": "usePlaybooks(options?)"
    },
    {
      "depth": 3,
      "slug": "userun",
      "text": "useRun()"
    },
    {
      "depth": 3,
      "slug": "useruneventsrunid",
      "text": "useRunEvents(runId)"
    },
    {
      "depth": 2,
      "slug": "components",
      "text": "Components"
    },
    {
      "depth": 3,
      "slug": "runstatusbadge",
      "text": "RunStatusBadge"
    },
    {
      "depth": 3,
      "slug": "runtimeline",
      "text": "RunTimeline"
    },
    {
      "depth": 3,
      "slug": "playbookcard",
      "text": "PlaybookCard"
    },
    {
      "depth": 2,
      "slug": "error-handling",
      "text": "Error handling"
    },
    {
      "depth": 2,
      "slug": "see-also",
      "text": "See also"
    }
  ],
  "body_markdown": "# Pilot React SDK\n\n`@cuitty/pilot-react` provides React hooks and pre-built components for the Pilot API. It wraps `@cuitty/pilot-sdk` with idiomatic React patterns — context providers, data-fetching hooks, and SSE subscriptions that clean up automatically.\n\n## Install\n\n```bash\nsfw bun add @cuitty/pilot-react\n# or\nsfw npm install @cuitty/pilot-react\n```\n\nPeer dependencies: `react>=18`, `@cuitty/pilot-sdk`.\n\n## Quick start\n\n```tsx\nimport { PilotProvider, usePlaybooks, useRun, useRunEvents } from \"@cuitty/pilot-react\";\n\nfunction App() {\n  return (\n    <PilotProvider baseUrl=\"http://localhost:4320\" auth={{ apiKey: \"pk_...\" }}>\n      <Dashboard />\n    </PilotProvider>\n  );\n}\n\nfunction Dashboard() {\n  const { data: playbooks, loading } = usePlaybooks();\n  const { run, start } = useRun();\n  const events = useRunEvents(run?.id);\n\n  if (loading) return <p>Loading...</p>;\n\n  return (\n    <div>\n      {playbooks?.map((pb) => (\n        <button key={pb.id} onClick={() => start({ playbookId: pb.id, mode: \"autonomous\" })}>\n          {pb.title}\n        </button>\n      ))}\n      {events.map((e, i) => (\n        <div key={i}>{e.type} {e.stepId}</div>\n      ))}\n    </div>\n  );\n}\n```\n\n## PilotProvider\n\nWraps your component tree with a `PilotClient` instance. Accepts all `PilotClientConfig` props plus `children`. The client is recreated when `baseUrl` or `auth.token` change, and closed on unmount.\n\n```tsx\nimport { PilotProvider } from \"@cuitty/pilot-react\";\n\n<PilotProvider\n  baseUrl=\"http://localhost:4320\"\n  auth={{ token: \"ey...\" }}\n  timeout={15000}\n>\n  {children}\n</PilotProvider>\n```\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `baseUrl` | `string` | Pilot server URL |\n| `auth` | `{ token?: string; cookie?: string; apiKey?: string }` | Authentication credentials |\n| `timeout` | `number` | Per-request timeout in ms (default 30000) |\n| `children` | `React.ReactNode` | Child components |\n\n### usePilot()\n\nReturns the `PilotClient` from context. Throws if used outside `<PilotProvider>`.\n\n```tsx\nimport { usePilot } from \"@cuitty/pilot-react\";\n\nconst pilot = usePilot();\nconst health = await pilot.health();\n```\n\n## Hooks\n\n### usePlaybooks(options?)\n\nFetches and caches the playbook list. Re-fetches when options change.\n\n```tsx\nconst { data, loading, error, refetch } = usePlaybooks();\nconst { data: cfOnly } = usePlaybooks({ target: \"cloudflare\" });\n```\n\n| Return | Type | Description |\n|--------|------|-------------|\n| `data` | `PlaybookSummary[] \\| null` | Fetched playbooks, `null` until loaded |\n| `loading` | `boolean` | `true` while fetching |\n| `error` | `Error \\| null` | Fetch error, if any |\n| `refetch` | `() => Promise<void>` | Manually re-fetch the list |\n\n### useRun()\n\nManages a single run lifecycle: start, abort, and refresh.\n\n```tsx\nconst { run, loading, error, start, abort, refresh } = useRun();\n\n// Start a new run\nconst result = await start({\n  playbookId: \"cloudflare.dns.add-a-record\",\n  mode: \"interactive\",\n  inputs: { zone: \"example.com\", record_name: \"api\", ip_address: \"1.2.3.4\" },\n});\n\n// Abort the active run\nawait abort();\n\n// Refresh run state from the server\nawait refresh();\n```\n\n| Return | Type | Description |\n|--------|------|-------------|\n| `run` | `Run \\| null` | Current run object |\n| `loading` | `boolean` | `true` while starting a run |\n| `error` | `Error \\| null` | Error from the last operation |\n| `start(req)` | `(StartRunRequest) => Promise<Run \\| null>` | Start a run and fetch its full details |\n| `abort()` | `() => Promise<void>` | Abort the current run |\n| `refresh()` | `() => Promise<void>` | Re-fetch current run state |\n\n### useRunEvents(runId)\n\nSubscribes to real-time SSE events for a run. Automatically unsubscribes on unmount or when `runId` changes. Returns a growing array of events.\n\n```tsx\nconst events = useRunEvents(run?.id);\n\n// events: RunEvent[]\nevents.forEach((event) => {\n  console.log(event.type, event.stepId);\n});\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `runId` | `string \\| null \\| undefined` | Run ID to subscribe to; `null`/`undefined` pauses subscription |\n\nReturns `RunEvent[]` — accumulates all events received since subscription started.\n\n## Components\n\n### RunStatusBadge\n\nRenders a colored pill badge for a run status.\n\n```tsx\nimport { RunStatusBadge } from \"@cuitty/pilot-react\";\n\n<RunStatusBadge status=\"running\" />\n<RunStatusBadge status=\"completed\" />\n<RunStatusBadge status=\"failed\" />\n```\n\nSupported statuses: `queued`, `running`, `awaiting_approval`, `completed`, `failed`, `aborted`.\n\n### RunTimeline\n\nRenders a vertical timeline of run events with color-coded borders (blue for in-progress, green for complete, red for failures).\n\n```tsx\nimport { RunTimeline } from \"@cuitty/pilot-react\";\n\nconst events = useRunEvents(runId);\n<RunTimeline events={events} />\n```\n\n### PlaybookCard\n\nDisplays a playbook summary card with an optional \"Run\" button.\n\n```tsx\nimport { PlaybookCard } from \"@cuitty/pilot-react\";\n\n<PlaybookCard\n  playbook={playbook}\n  onRun={(pb) => start({ playbookId: pb.id, mode: \"autonomous\" })}\n/>\n```\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `playbook` | `PlaybookSummary` | Playbook to display |\n| `onRun` | `(playbook: PlaybookSummary) => void` | Optional callback when \"Run\" is clicked |\n\n## Error handling\n\nErrors from hooks are captured in the `error` field rather than thrown. For direct `PilotClient` usage via `usePilot()`, catch `PilotApiError` and `PilotConnectionError` from `@cuitty/pilot-sdk`.\n\n```tsx\nimport { PilotApiError, PilotConnectionError } from \"@cuitty/pilot-sdk\";\n\nconst pilot = usePilot();\ntry {\n  await pilot.runs.start({ playbookId: \"nonexistent\" });\n} catch (err) {\n  if (err instanceof PilotApiError) {\n    console.error(`API ${err.status}: ${err.statusText}`, err.body);\n  } else if (err instanceof PilotConnectionError) {\n    console.error(\"Cannot reach Pilot:\", err.message);\n  }\n}\n```\n\n## See also\n\n- [JavaScript SDK](/docs/pilot/sdk/javascript) — underlying `PilotClient` API reference\n- [Playbook reference](/docs/pilot/playbook-reference) — YAML schema for playbook documents\n- [Quickstart](/docs/pilot/quickstart) — record and replay your first workflow",
  "links_out": [
    "/docs/pilot/sdk/javascript",
    "/docs/pilot/playbook-reference",
    "/docs/pilot/quickstart"
  ]
}