ZeptapDocs

Output and exit codes

Where zeptap saves screenshots, how @t refs work, the JSON it prints with --json, and what each exit code means.

Text output

Every action prints what happened, then key: value details, then the screenshot's path, then the screen's text if --look was set:

[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)
text (3 lines, @tN  x,y  text):
@t1  295,88  Reels
@t2  120,1188  Home
@t3  412,1188  Reels

On success the output goes to stdout; on failure it goes to stderr, with a non-zero exit code. acquire is the exception: stdout is only the lease id, so LEASE=$(zeptap acquire ...) works.

Screenshots

Screenshots go to ./.zeptap/shots/ in the working directory, numbered (0001.jpg, 0002.jpg, ...) and limited to the last 50. The folder ignores itself in git. Agents' file readers allow the working directory without asking, which is why it's the default.

  • ZEPTAP_OUT_DIR uses another folder.
  • -o <path> saves one file. A .png path saves a PNG.
  • --no-shot skips the screenshot.
  • If the working directory isn't writable, they go to $TMPDIR/zeptap/.

Refs

look numbers the lines it reads as @t1, @t2, and so on, top to bottom, and remembers them for that phone in .zeptap/state.json. tap @t4 checks that the text is still where it was before tapping:

  • If the text moved a little, it taps the new spot.
  • If it went away, the tap is refused with exit code 3, and the agent runs look again instead of tapping a guess.

Any action with --look refreshes the refs, as does screenshot --annotate, which draws each ref on the image.

JSON

--json prints one object on stdout instead of text, whether the command succeeds or fails:

{"ok":true,"message":"[Test iPhone] tap done; settled in 540 ms","phone":{"id":"A1B2","name":"Test iPhone"},
 "screenshot":{"path":"/…/.zeptap/shots/0042.jpg","width":591,"height":1280},"details":["target: \"Reels\" (412,1188)"]}
FieldWhen
okAlways. true or false
messageAlways. What happened, or why it failed
codeOn failure: failed, usage, not_found, unreachable, unavailable, timeout, needs_human, sandboxed or busy
phoneWhen a phone was used: its id and name
screenshotWhen one was saved: path, width, height
linesFrom look, --look and screenshot --annotate: each line's ref, text, center and box
dataFrom phones, acquire, leases, doctor, skill list, tools, version and run
detailsExtra lines, such as the target of a tap

Exit codes

CodeJSON codeMeaningWhat to do
0Done
1failedFailedRead the message
2usageBad arguments, or the target was ambiguous (several text matches, several phones)Fix the call. Pick a match with --index or a ref, or a phone with -p
3not_foundText, a ref (stale or missing), or an app wasn't found. Nothing was doneRun look again
4unreachableZeptap isn't running and couldn't be openedAsk the user to open Zeptap
5unavailableThe phone isn't ready: Bluetooth, USB, or lockedunlock if locked; otherwise see Troubleshooting
6timeoutTimed outRetry, or raise --timeout
7needs_humanNeeds the user: the license, pairing, a permissionTell the user
8sandboxedAn agent sandbox blocked the connection to ZeptapSee Agent sandboxes
9busyThe phone is leased to another agentWait with acquire --wait, or use another phone

The message always says what to do next.

On this page