ghosthand CLI reference

Install

1npx ghosthand --help

Agent loop

1. ghosthand list (which iPhones, locked, leased by whom)
   ghosthand acquire -d <id> --label <session id> --reason "<task>" (prints e.g. studio:42 (42 below))
2. ghosthand screentext -l 42 (read text and boxes (cheap, no image))
   ghosthand screenshot -l 42 -o s.png (or look at the screen (~500 tokens))
3. ghosthand tap -l 42 --text "Label" --screenshot s.png --screentext
ghosthand tap -l 42 <x> <y> --screenshot s.png --screentext (x,y read from s.png)
4. read the printed text and s.png, decide the next action toward the task, repeat 3
5. ghosthand release -l 42 (when the task is done)

Global options

Commands

Leases

Screen

Input

Tasks

iPhone

Recording

Files, photos and apps

Setup and account

Tunnel and scripts

Daemon

Random values

Agent manual

• Ghosthand app windows are user-only. Never interact with them for the user.
• Missing macOS Camera or Bluetooth permission: run ghosthand setup once and tell the user to complete setup in the small Ghosthand window. Poll setup status every 2 seconds until ready is true, then continue automatically. Do not request permissions yourself. No normal command or preview shows permission dialogs.
• Leases: every command that uses an iPhone needs one (list does not). Always pass --reason with your task. An iPhone leased by someone else fails at once and shows the label, reason, and how long ago it was acquired and last used. Decide: give up or tell the user, or run ghosthand wait. Never --force unless its holder is gone. A lease ends after 10 min without a command. Pass -l explicitly: tool-call environments may not persist. --label is display only.
• --wait-text checks a known expected text after input, with --timeout-ms 1...60000 (default 5000). A timeout says input was sent; never repeat input automatically. Already-present matching text does not prove the action caused a transition.
• Non-English phone: export GHOSTHAND_LANGUAGE=it-IT (or pass --language) once, so screentext and tap --text read accents and local words right.
• Coordinates are screen points by default: the numbers you read in a screenshot or in screentext are the numbers you send to tap/swipe. Never rescale them yourself.
• Add --screenshot and/or --screentext to every action: they wait until the screen is still, then save the image / print the text. No separate screenshot call.
• Before type, read a screenshot: the cursor must be in the field you want. Keys go to the focused field (in Messages, Enter in To: keeps focus there).
• Leave the iPhone unlocked when done. Locked phones give no screenshots. The daemon keeps every unlocked USB- and Bluetooth-connected iPhone awake (a Control key press after 10 s idle). Locked or unplugged iPhones get no key, so Auto-Lock works normally.
• A wrong unlock passcode is never retried (failed attempts count toward lockout).
• Account: acquire needs this Mac signed in to ghosthand.dev. The free plan covers one iPhone. login-required: run ghosthand setup, tell the user to sign in there, poll setup status. subscription-required: show the user the links in the error, acquire again after they change the plan; never retry in a loop. Do not run account login yourself.
• New account and the user gave no details: get each from ghosthand random <kind> (name, lastname, username, birthdate, password). Never invent a password. Every value is saved: ghosthand random list finds one you forgot.
• ghosthand drives the iPhone as a Bluetooth keyboard and mouse, so iOS keyboard shortcuts work with key: cmd+a then backspace clears a field, alt+backspace, cmd+shift+left, cmd+c, cmd+z, fn+h (Home), fn+up (App Switcher), fn+c (Control Center), fn+n (notifications). Full list: ghosthand key --help.
• Go Home with key home, not the AssistiveTouch menu.
• Screen shrunk to the bottom half (iOS Reachability), sheets look stale: tap the empty top area (tap 207 100) to restore it. Check this before anything else.
• Screen dimmed but no dialog in the screenshot: the dialog is hidden from USB capture. screenshot --native takes a real iOS screenshot (cmd+shift+3) that shows it, at the same coordinates tap takes. A button that ignores tap: press it once more (tap or hold x y --duration 400); a just-opened alert can ignore the first press.
• Long press (context menus, Home Screen icon menu, previews): hold x y. Move an item that needs a long press first (Home Screen icons): hold-drag --hold 2500.
• Files, photos, apps, battery and logs go over USB without the screen: file list, file pull, file push, photo list, photo pull, app list, info, logs (see each --help). To add a photo or video to Photos: ghosthand upload <file>, then Safari (upload --help).
• Dialog not responding or invisible to capture: try lock, then unlock once to dismiss it without accepting an option (tested on an XR, iOS 18.7). First obtain a user-confirmed passcode and pipe it to unlock --stdin. Without one, ask the user before locking. Check the screen afterward; this may not dismiss every dialog. Never retry a failed passcode or guess hidden taps.
• Scroll far with scroll down <ticks> (mouse wheel, ~100 pt per tick). swipe moves content by the drag length (no momentum): use it for pages and short moves.
• Swipe Home Screen pages from empty space or an icon, not from a widget, the dock or the AssistiveTouch button.
• Open an app: key cmd+space, type <app name>, key enter (works from any app; tested on an SE2, iOS 18.6). Faster than swiping Home Screen pages.
• An iPhone in XCTest mode (list shows xctest) takes the same commands through Apple's UI testing instead of Bluetooth. No lock, unlock, mute or shortcuts there; see control --help. Switch modes only when the user asks.
• On errors, read the whole message: it says what failed and what to do.
• No iPhone in list, or errors about USB, Trust, a never-paired iPhone, or Bluetooth that never connects: the user must connect or fix the phone. Run ghosthand setup once (MCP: use the setup tool). Tell the user to complete setup in the small Ghosthand window. All actions in the Ghosthand app window are user-only. Agents must not interact with the window or complete setup for the user. Poll ghosthand setup status (MCP: setup-status) every 2 seconds until ready is true. Pass --device (MCP: device) for the intended iPhone if known or if several are connected; use the returned device id on later polls. When ready, acquire that phone using its captureId from overview. Wait while the user completes setup, then continue automatically when ready. Do not reopen setup, request permissions, or retry input while waiting. If setup is still incomplete after 10 minutes, report the current status instead of retrying forever. Do not tap Trust or pair for them. A locked iPhone that is trusted and paired is not a setup problem: use unlock only with a passcode the user confirmed, otherwise ask the user to unlock it. ghosthand dashboard is a window to watch every iPhone and its agent; open it only if the user asks to see it.
• No clever loops that wait for a text you guess ("Open", "Done"): the next screen is hard to predict (App Store "Install" confirm, "requires a newer iOS", alerts). Loop only when a skill or document you follow says so. Otherwise: one action, read the whole screen, decide the next action.