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

ghosthand record start

Usage

ghosthand record start <path>

Options

OptionDescription
--fps [n]Frame rate cap, 1 up to the iPhone's rate (usually 60). Default: every frame
--max-duration [s]Stop by itself after this many seconds, 1-3600 (default: 300)
--no-audioRecord the screen only, no sound
Also takes the global options.

Details

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.

Examples

$ ghosthand record start -l 42 /tmp/demo.mov
$ ghosthand record start -l 42 /tmp/demo.mp4 --fps 30 --max-duration 60

MCP tool

The same command is the MCP tool record-start; flags are arguments.