CLI overview
The zeptap command drives your iPhone from any shell. It saves screenshots as files, reads the screen as text with refs, holds phones with leases, batches steps, and returns exit codes agents can act on.
zeptap is a command line tool that ships inside the Mac app. It drives the same iPhones as the MCP server, through the running app, so anything with a shell can use it: Claude Code, Codex, Gemini CLI, OpenCode, Aider, scripts, cron jobs and CI.
zeptap phones # which iPhones are paired, and whether they're ready
zeptap look # the screen's text, one line per label, each with a @t ref
zeptap tap @t4 --look # tap it, wait for the screen to settle, print the new screen's text
zeptap screenshot # save the screen as a JPEG and print its pathInstall
Nothing to install separately. Open Zeptap once from your Applications folder and it links ~/.local/bin/zeptap. Then check everything:
zeptap doctorInstall and connect agents covers PATH, Homebrew, the Beta build, agent skills and sandboxes.
Agent loop
zeptap phoneslists the iPhones, whether each is ready, and who holds it.zeptap acquire --reason "<task>"holds one and prints a lease id.zeptap look -l 7reads the screen as text, one line per label, each with a@tref.zeptap screenshot -l 7saves an image for when text isn't enough.zeptap tap -l 7 @t4 --lookacts.--lookprints the new screen's text in the same call.- Read what it printed, decide, and repeat step 3.
zeptap release -l 7when done.
zeptap phones
zeptap acquire --reason "warm up @sara_runs on Instagram" # prints a lease id, e.g. 7
zeptap open Instagram -l 7
zeptap look -l 7
zeptap tap -l 7 @t3 --look
zeptap release -l 7Every action waits for the screen to stop moving, then prints what happened and saves a screenshot:
[Test iPhone] tap done; settled in 540 ms
target: "Reels" (412,1188)
screenshot: /Users/you/project/.zeptap/shots/0042.jpg (591x1280 px; tap coordinates are pixels in it)Coordinates are pixels in that screenshot, origin top-left. The MCP tools use the same space.
CLI or MCP
Both drive the phone the same way and share one set of tools. Pick by agent:
| CLI | MCP | |
|---|---|---|
| Works in | Any agent or script with a shell | Clients with MCP support, including Claude Desktop and ChatGPT, which have no shell |
| Screenshots | Saved as files: the agent opens one only when text isn't enough | An image with every action |
| Reading the screen | look prints text with @t refs, much cheaper than an image | find_text |
| Many steps | run does a whole sequence in one call | One call per action |
| Setup | On PATH automatically; agents learn it from a skill | One click in Settings › Connectors |
Agents that only need to know what's on screen use far fewer tokens with look than with an image per action. For a model that relies on seeing each screen, MCP works just as well. Give an agent one or the other, not both: two sets of instructions for one phone tend to confuse it.
Global options
Every command that acts on a phone takes these:
| Option | Description |
|---|---|
-l, --lease <id> | Act on the phone this lease holds. Env: ZEPTAP_LEASE |
-p, --phone <id or name> | Act on this phone. Env: ZEPTAP_PHONE. Default: the only paired phone, else the one active in Zeptap |
-o, --out <path> | Save the screenshot here instead of ./.zeptap/shots/NNNN.jpg. A .png path saves a PNG |
--no-shot | Don't save a screenshot after the action |
--look | Also print the screen's text, with @t refs, after the action |
--settle-ms <ms> | Longest wait for the screen to settle (default 3000; about 800 in video feeds) |
--json | Print one JSON object on stdout, success or failure. See Output |
-h, --help | Print the full manual, written for agents |
-v, --version | Print the command's and the app's versions |
Unknown options fail with exit code 2 rather than being ignored, so an agent that guessed a flag finds out. Durations such as --timeout, --wait and --idle-timeout take 10, 10s, 1500ms or 2m.
Commands
Phones and leases
| Command | What it does |
|---|---|
phones | List the paired iPhones: id, name, model, whether each is ready, and its lease |
acquire | Hold a phone so no other agent drives it. Prints the lease id |
release | Give a held phone back |
leases | List the leases currently held |
Seeing
| Command | What it does |
|---|---|
look | Read the screen with OCR: one line per label, with a @t ref and its center |
screenshot | Save the settled screen as a JPEG and print its path |
wait | Wait a set time, or until text shows up or goes away |
Touch
| Command | What it does |
|---|---|
tap | Tap a point, a @t ref or a line of text |
double-tap | Double-tap the same kinds of target |
long-press | Press and hold |
drag | Drag from one point to another, with no momentum |
flick | A fast swipe with momentum |
Keyboard and navigation
| Command | What it does |
|---|---|
type | Type text into the focused field |
key | Press a key, with modifiers |
open | Open an app by the name under its icon |
home | Go to the Home Screen |
back | Go back one screen |
dismiss | Close Spotlight, menus, sheets or the keyboard |
lock | Lock the iPhone |
unlock | Unlock with the passcode saved in Zeptap |
Batching and tools
| Command | What it does |
|---|---|
run | Run several steps in one call |
call | Call any MCP tool by name |
tools | List the MCP tools |
Setup
| Command | What it does |
|---|---|
skill | List and load Zeptap's skills, and install the skill that teaches agents this command |
doctor | Check the command, PATH, the app, the connection, the license, the phones and the agent skills |
version | Print the command's and the app's versions |
mcp | Run the MCP server over stdio, for clients that only launch commands |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Done |
| 1 | Failed: read the message |
| 2 | Bad arguments, or the target was ambiguous (several text matches, several phones) |
| 3 | Not found: text, a ref (stale or missing), or an app. Nothing was done |
| 4 | Zeptap isn't running and couldn't be opened |
| 5 | The phone isn't ready: Bluetooth, USB, or locked |
| 6 | Timed out |
| 7 | Needs the user: the license, pairing, a permission |
| 8 | An agent sandbox blocked the connection to Zeptap |
| 9 | The phone is leased to another agent |
Output covers screenshots, refs, JSON and these codes in more depth.
Environment variables
| Variable | Effect |
|---|---|
ZEPTAP_LEASE | Default for -l, --lease |
ZEPTAP_PHONE | Default for -p, --phone |
ZEPTAP_OUT_DIR | Folder for screenshots and ref state, instead of ./.zeptap |
Agent manual
zeptap --help prints the manual for the version installed on this Mac, followed by the skills turned on in Zeptap. The skill Zeptap installs for agents tells them to read it first, so the instructions always match the command. The rules it gives agents:
- Read before you act:
lookis cheap text. Open a screenshot for icons, images and layout. - Coordinates are pixels in the screenshot image. Send the numbers you read; don't rescale. Tap the center of controls, and prefer
@trefs or--textover estimated coordinates. - A
@tref is checked before use. If its text moved away, the tap is refused with exit code 3: runlookagain. - Use
--expect <text>where a mis-tap posts, sends or deletes. typeneeds a focused field, and iOS autocorrect may change the text, so check it.- On a locked phone, run
unlockonce. Never type a passcode. - Don't submit, send, buy or delete anything the user didn't ask for. A tap on a button that pays waits for the user to approve it on the Mac.
- Zeptap's own windows belong to the user. Never click or type in them.
The driving rules apply as they do over MCP.
Driving the iPhone
The operating loop and calibrated rules that make an agent reliable on a real iPhone - targeting, scrolling, typing, recovery and safety.
Install and connect agents
How the zeptap command gets on your PATH, how to teach Claude Code, Codex and Cursor to use it, and how it gets through agent sandboxes.