Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

record-start

record-startTOOL
Start recording the iPhone screen and sound to a new .mov or .mp4 file. Stops by itself after 5 minutes; stop earlier with record stop
Returns at once; the recording runs in the daemon while you send input. Use any other command meanwhile: screenshots, screentext and taps keep working.
  • Local CLI and Unix-socket HTTP: the file is written on this Mac. The CLI makes a relative path absolute against its own folder. The folder must exist and the file must not: a recording never overwrites a file. Remote HTTP cannot choose a Mac path.
  • MCP: omit path. The daemon owns a temporary file; record-stop returns an embedded resource blob up to 16 MiB, or a 1-day upload link up to 100 MB. Larger files need local collection on the Mac. Upload failures keep the recording for another record-stop while the lease is active. Delivery, a new recording or lease end removes temporary files.
  • It stops by itself, and the file is complete, after --max-duration, when the lease ends (release, idle timeout, --force), or when the daemon stops. Run record stop to get its size and duration.
  • The lease idle timeout still counts: send a command at least every 10 minutes (or acquire with a longer --idle-timeout), or the lease ends and so does the recording.
  • One recording per iPhone at a time. A locked iPhone cannot start one.
  • Video is H.264 at the native screen size (828x1792 on an XR); sound is AAC. Size measured on an XR: 3-5 MB per minute on a still screen, at most about 17 MB per minute while the screen moves. --fps 30 lowers both.
  • A dark display sends no frames: start fails with no-frame. Run wake first.
  • The sound track is the iPhone's sound output. It is silent when nothing plays.
  • With sound, record start and record stop pause media that is playing on the iPhone (iOS audio route change; tested on iOS 18.7). Start the recording first, then start playback; or press play again after record start. --no-audio does not pause it.
  • The round AssistiveTouch button is in the video unless "Always Show Menu" is off (Settings > Accessibility > Touch > AssistiveTouch). USB cannot change that setting; ask the user before you change it in Settings. The mouse pointer dot stays in the video.
CLI flags in this text are arguments: --fps = fps, --max-duration = maxDurationSeconds, --no-audio = audio: false
Parameters
audio?boolean
Record the iPhone's sound too (default: true)
fps?number
Frame rate cap, 1 up to the iPhone's rate (usually 60). Default: every frame
lease *string
Lease id exactly as acquire printed it, e.g. "studio:42"
mac?string
Mac slug from list, e.g. "studio". Needed when several Macs are online
maxDurationSeconds?number
Stop by itself after this many seconds, 1-3600 (default: 300)
Request example
{
  "method": "tools/call",
  "params": {
    "name": "record-start",
    "arguments": {
      "audio": true,
      "fps": 0,
      "lease": "string",
      "mac": "string",
      "maxDurationSeconds": 0
    }
  }
}