Welles
Reference

Welles API & CLI

Three ways to drive Welles from a process other than the macOS app: the reel CLI, the raw HTTP API, or as a Claude Code skill that an agent triggers automatically when the user asks for it.

Authentication

Every endpoint requires a bearer token in the Authorization header. Sign in once through the macOS app or run reel login and the CLI manages the credential for you on subsequent calls.

Base URL

https://reel-api-zqli.onrender.com

AI

Script generation (OpenAI / Anthropic) and voiceover synthesis (ElevenLabs). The macOS app uses these to draft narration and render TTS for any recording.

POST/ai/script

Generate script

Drafts a teleprompter-ready narration script for a Welles screen recording. Picks length, audience, and style flags so you can dial the tone without re-prompting.

Body
  • topicstringoptional

    What the recording is about. Optional but improves results.

  • lengthenumoptional

    concise | default | verbose

  • audienceenumoptional

    technical | non_technical

  • styleenumoptional

    concise_no_adjectives | default | flowery

  • providerenumrequired

    openai or anthropic

  • model_idstringoptional

    Override the default model for the chosen provider.

  • video_iduuidoptional

    Optional binding so the script is associated with a recording.

  • visible_code_summarystringoptional

    Short description of code on screen — sharpens the script.

  • source_contextstringoptional

    Code snippets to ground the narration in. Requires source_context_consent=true.

cURL
curl -X POST $REEL_API/ai/script \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Walking through the new auth flow",
    "length": "default",
    "audience": "technical",
    "style": "default",
    "provider": "anthropic"
  }'
Response
{
  "script": "Here's a quick tour of the new auth flow…",
  "provider": "anthropic",
  "model_id": "claude-sonnet-4-6",
  "billing_class": "premium"
}
POST/ai/voiceover

Generate voiceover

Renders a voiceover via ElevenLabs TTS. Returns base64 MP3 so the client can drop it straight onto the recording's voiceover track.

Body
  • voice_idstringrequired

    ElevenLabs voice id.

  • textstringrequired

    Narration text to synthesize.

  • video_iduuidoptional

    Optional binding so the result is associated with a recording.

  • model_idstringoptional

    Defaults to ElevenLabs' fast multilingual model.

  • lengthenumoptional

    concise | default | verbose — passes through to the script style guide.

cURL
curl -X POST $REEL_API/ai/voiceover \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "text": "Welcome back."
  }'
Response
{
  "audio_base64": "<MP3 bytes, base64-encoded>",
  "model_id": "eleven_flash_v2_5",
  "billing_class": "premium"
}
Agent workflows

Local CLI commands that drive the macOS app end-to-end. They use Accessibility, ScreenCaptureKit, and the reel:// deep link instead of an HTTP endpoint, so they're CLI-only — but they pair perfectly with Claude Code skills.

CLI

Record a demo

The flagship pipeline. Generates a source-aware script, renders a voiceover, opens Welles via reel://agent-record, drives the recording, exports the MP4, and uploads a hosted share — in one command.

Body
  • project_iduuidrequired

    Welles project to attach the recording to.

  • --sourceenumoptional

    display | window | app — what to capture.

  • --targetstringoptional

    App / window name to match. Pair with --window-id for unambiguous capture.

  • --durationsecondsoptional

    How long to record. Defaults to a sane preset per scenario.

  • --scenariostringoptional

    Named local interaction plan, e.g. reel-self-demo.

  • --auto-storyboardflagoptional

    Have the CLI infer an action plan from the live UI tree.

  • --control-modeenumoptional

    cli | virtual | human | none — who drives the demo.

  • --topicstringoptional

    One-line description that grounds the script.

  • --providerenumoptional

    openai | anthropic. Defaults to anthropic.

  • --voice-idstringoptional

    ElevenLabs voice for the narration.

  • --source-contextpathoptional

    Path to local code grounding context. Requires --source-context-consent.

cURL
# CLI-only — drives macOS Accessibility + capture locally,
# no HTTP equivalent. See the CLI tab for the invocation.
Response
{
  "share": { "url": "https://welles.app/s/8a4e2…", "permission": "view" },
  "video_id": "<uuid>",
  "script_chars": 612,
  "voiceover_seconds": 17.8,
  "duration_seconds": 17.9
}
CLI

Plan an interaction

Builds a JSON action plan from a live app's Accessibility tree (and optional repo context). Steps include click targets, narration cues, and timing — drop the file straight into `reel record --action-plan`.

Body
  • --sourceenumrequired

    display | window | app.

  • --targetstringoptional

    App or window name to match.

  • --scenariostringoptional

    Named scenario, e.g. reel-self-demo.

  • --repo-pathpathoptional

    Local repo for source-aware planning hints. Nothing is uploaded.

  • --control-modeenumoptional

    cli | virtual | human | none.

  • --max-stepsintegeroptional

    Cap on how many steps the planner can emit.

cURL
# CLI-only — drives macOS Accessibility + capture locally,
# no HTTP equivalent. See the CLI tab for the invocation.
Response
{
  "scenario": "reel-self-demo",
  "control_mode": "cli",
  "steps": [
    { "t": 0.0, "narration": "Open the recorder…",
      "action": { "click": { "selector": "button:New Recording" } } },
    { "t": 2.2, "narration": "Pick a window to capture",
      "action": { "type": { "text": "Welles" } } }
  ]
}
CLI

List capture sources

Discovery for everything Welles can record on this Mac — displays, apps, and individual windows with their CGWindowIDs and bundle IDs. Use the IDs to lock the recorder onto exactly one target.

Body
  • --querystringoptional

    Filter by source name, bundle ID, or window title.

cURL
# CLI-only — drives macOS Accessibility + capture locally,
# no HTTP equivalent. See the CLI tab for the invocation.
Response
{
  "displays": [{ "id": 1, "size": [3024, 1964] }],
  "apps":     [{ "name": "Welles", "bundle_id": "xyz.lonelyheartsclub.Reel", "pid": 74902 }],
  "windows":  [{ "id": 12345, "title": "Editor — onboarding-demo", "app": "Welles" }]
}
CLI

Inspect UI controls

Dumps the Accessibility tree for an app or window with normalized coordinates, roles, and labels — so an agent can target real buttons by name instead of guessing pixel positions.

Body
  • --app-namestringoptional

    Owning app to inspect.

  • --window-titlestringoptional

    Window/tab title filter.

  • --window-idintegeroptional

    Exact CGWindowID from `reel sources`.

  • --querystringoptional

    Filter UI elements by text or role.

  • --max-depthintegeroptional

    Cap on tree-walk recursion.

  • --max-elementsintegeroptional

    Cap on emitted elements.

cURL
# CLI-only — drives macOS Accessibility + capture locally,
# no HTTP equivalent. See the CLI tab for the invocation.
Response
{
  "elements": [
    { "id": "AXButton-12", "role": "AXButton",
      "label": "New Recording", "frame": [0.06, 0.04, 0.10, 0.02] }
  ]
}