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 ReelsOn 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_DIRuses another folder.-o <path>saves one file. A.pngpath saves a PNG.--no-shotskips 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
lookagain 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)"]}| Field | When |
|---|---|
ok | Always. true or false |
message | Always. What happened, or why it failed |
code | On failure: failed, usage, not_found, unreachable, unavailable, timeout, needs_human, sandboxed or busy |
phone | When a phone was used: its id and name |
screenshot | When one was saved: path, width, height |
lines | From look, --look and screenshot --annotate: each line's ref, text, center and box |
data | From phones, acquire, leases, doctor, skill list, tools, version and run |
details | Extra lines, such as the target of a tap |
Exit codes
| Code | JSON code | Meaning | What to do |
|---|---|---|---|
| 0 | Done | ||
| 1 | failed | Failed | Read the message |
| 2 | usage | Bad 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 |
| 3 | not_found | Text, a ref (stale or missing), or an app wasn't found. Nothing was done | Run look again |
| 4 | unreachable | Zeptap isn't running and couldn't be opened | Ask the user to open Zeptap |
| 5 | unavailable | The phone isn't ready: Bluetooth, USB, or locked | unlock if locked; otherwise see Troubleshooting |
| 6 | timeout | Timed out | Retry, or raise --timeout |
| 7 | needs_human | Needs the user: the license, pairing, a permission | Tell the user |
| 8 | sandboxed | An agent sandbox blocked the connection to Zeptap | See Agent sandboxes |
| 9 | busy | The phone is leased to another agent | Wait with acquire --wait, or use another phone |
The message always says what to do next.