ZeptapDocs

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 path

Install

Nothing to install separately. Open Zeptap once from your Applications folder and it links ~/.local/bin/zeptap. Then check everything:

zeptap doctor

Install and connect agents covers PATH, Homebrew, the Beta build, agent skills and sandboxes.

Agent loop

  1. zeptap phones lists the iPhones, whether each is ready, and who holds it. zeptap acquire --reason "<task>" holds one and prints a lease id.
  2. zeptap look -l 7 reads the screen as text, one line per label, each with a @t ref. zeptap screenshot -l 7 saves an image for when text isn't enough.
  3. zeptap tap -l 7 @t4 --look acts. --look prints the new screen's text in the same call.
  4. Read what it printed, decide, and repeat step 3.
  5. zeptap release -l 7 when 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 7

Every 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:

CLIMCP
Works inAny agent or script with a shellClients with MCP support, including Claude Desktop and ChatGPT, which have no shell
ScreenshotsSaved as files: the agent opens one only when text isn't enoughAn image with every action
Reading the screenlook prints text with @t refs, much cheaper than an imagefind_text
Many stepsrun does a whole sequence in one callOne call per action
SetupOn PATH automatically; agents learn it from a skillOne 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:

OptionDescription
-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-shotDon't save a screenshot after the action
--lookAlso 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)
--jsonPrint one JSON object on stdout, success or failure. See Output
-h, --helpPrint the full manual, written for agents
-v, --versionPrint 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

CommandWhat it does
phonesList the paired iPhones: id, name, model, whether each is ready, and its lease
acquireHold a phone so no other agent drives it. Prints the lease id
releaseGive a held phone back
leasesList the leases currently held

Seeing

CommandWhat it does
lookRead the screen with OCR: one line per label, with a @t ref and its center
screenshotSave the settled screen as a JPEG and print its path
waitWait a set time, or until text shows up or goes away

Touch

CommandWhat it does
tapTap a point, a @t ref or a line of text
double-tapDouble-tap the same kinds of target
long-pressPress and hold
dragDrag from one point to another, with no momentum
flickA fast swipe with momentum

Keyboard and navigation

CommandWhat it does
typeType text into the focused field
keyPress a key, with modifiers
openOpen an app by the name under its icon
homeGo to the Home Screen
backGo back one screen
dismissClose Spotlight, menus, sheets or the keyboard
lockLock the iPhone
unlockUnlock with the passcode saved in Zeptap

Batching and tools

CommandWhat it does
runRun several steps in one call
callCall any MCP tool by name
toolsList the MCP tools

Setup

CommandWhat it does
skillList and load Zeptap's skills, and install the skill that teaches agents this command
doctorCheck the command, PATH, the app, the connection, the license, the phones and the agent skills
versionPrint the command's and the app's versions
mcpRun the MCP server over stdio, for clients that only launch commands

Exit codes

CodeMeaning
0Done
1Failed: read the message
2Bad arguments, or the target was ambiguous (several text matches, several phones)
3Not found: text, a ref (stale or missing), or an app. Nothing was done
4Zeptap isn't running and couldn't be opened
5The phone isn't ready: Bluetooth, USB, or locked
6Timed out
7Needs the user: the license, pairing, a permission
8An agent sandbox blocked the connection to Zeptap
9The phone is leased to another agent

Output covers screenshots, refs, JSON and these codes in more depth.

Environment variables

VariableEffect
ZEPTAP_LEASEDefault for -l, --lease
ZEPTAP_PHONEDefault for -p, --phone
ZEPTAP_OUT_DIRFolder 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: look is 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 @t refs or --text over estimated coordinates.
  • A @t ref is checked before use. If its text moved away, the tap is refused with exit code 3: run look again.
  • Use --expect <text> where a mis-tap posts, sends or deletes.
  • type needs a focused field, and iOS autocorrect may change the text, so check it.
  • On a locked phone, run unlock once. 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.

On this page