{ "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 \n \n \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

Loading...

;\n\n return (\n
\n {playbooks?.map((pb) => (\n \n ))}\n {events.map((e, i) => (\n
{e.type} {e.stepId}
\n ))}\n
\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\n {children}\n\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 ``.\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` | 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` | Start a run and fetch its full details |\n| `abort()` | `() => Promise` | Abort the current run |\n| `refresh()` | `() => Promise` | 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\n\n\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\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 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", "body_html": "

Pilot React SDK

\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

Install

\n
sfw bun add @cuitty/pilot-react\n# or\nsfw npm install @cuitty/pilot-react
\n

Peer dependencies: react>=18, @cuitty/pilot-sdk.

\n

Quick start

\n
import { 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

PilotProvider

\n

Wraps 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
import { 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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropTypeDescription
baseUrlstringPilot server URL
auth{ token?: string; cookie?: string; apiKey?: string }Authentication credentials
timeoutnumberPer-request timeout in ms (default 30000)
childrenReact.ReactNodeChild components
\n

usePilot()

\n

Returns the PilotClient from context. Throws if used outside <PilotProvider>.

\n
import { usePilot } from \"@cuitty/pilot-react\";\n\nconst pilot = usePilot();\nconst health = await pilot.health();
\n

Hooks

\n

usePlaybooks(options?)

\n

Fetches and caches the playbook list. Re-fetches when options change.

\n
const { data, loading, error, refetch } = usePlaybooks();\nconst { data: cfOnly } = usePlaybooks({ target: \"cloudflare\" });
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ReturnTypeDescription
dataPlaybookSummary[] | nullFetched playbooks, null until loaded
loadingbooleantrue while fetching
errorError | nullFetch error, if any
refetch() => Promise<void>Manually re-fetch the list
\n

useRun()

\n

Manages a single run lifecycle: start, abort, and refresh.

\n
const { 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\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ReturnTypeDescription
runRun | nullCurrent run object
loadingbooleantrue while starting a run
errorError | nullError from the last operation
start(req)(StartRunRequest) => Promise<Run | null>Start a run and fetch its full details
abort()() => Promise<void>Abort the current run
refresh()() => Promise<void>Re-fetch current run state
\n

useRunEvents(runId)

\n

Subscribes to real-time SSE events for a run. Automatically unsubscribes on unmount or when runId changes. Returns a growing array of events.

\n
const events = useRunEvents(run?.id);\n\n// events: RunEvent[]\nevents.forEach((event) => {\n  console.log(event.type, event.stepId);\n});
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParamTypeDescription
runIdstring | null | undefinedRun ID to subscribe to; null/undefined pauses subscription
\n

Returns RunEvent[] — accumulates all events received since subscription started.

\n

Components

\n

RunStatusBadge

\n

Renders a colored pill badge for a run status.

\n
import { RunStatusBadge } from \"@cuitty/pilot-react\";\n\n<RunStatusBadge status=\"running\" />\n<RunStatusBadge status=\"completed\" />\n<RunStatusBadge status=\"failed\" />
\n

Supported statuses: queued, running, awaiting_approval, completed, failed, aborted.

\n

RunTimeline

\n

Renders a vertical timeline of run events with color-coded borders (blue for in-progress, green for complete, red for failures).

\n
import { RunTimeline } from \"@cuitty/pilot-react\";\n\nconst events = useRunEvents(runId);\n<RunTimeline events={events} />
\n

PlaybookCard

\n

Displays a playbook summary card with an optional “Run” button.

\n
import { PlaybookCard } from \"@cuitty/pilot-react\";\n\n<PlaybookCard\n  playbook={playbook}\n  onRun={(pb) => start({ playbookId: pb.id, mode: \"autonomous\" })}\n/>
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PropTypeDescription
playbookPlaybookSummaryPlaybook to display
onRun(playbook: PlaybookSummary) => voidOptional callback when “Run” is clicked
\n

Error handling

\n

Errors 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
import { 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

See also

\n", "links_out": [ "/docs/pilot/sdk/javascript", "/docs/pilot/playbook-reference", "/docs/pilot/quickstart" ] }