# Output and exit codes

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

Source: https://zeptap.com/docs/cli/output



## Text output [#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:

```txt
[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`](https://zeptap.com/docs/cli/commands/acquire) is the exception: stdout is only the lease id, so `LEASE=$(zeptap acquire ...)` works.

## Screenshots [#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 [#refs]

[`look`](https://zeptap.com/docs/cli/commands/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]

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

```json
{"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 [#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](https://zeptap.com/docs/reference/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](https://zeptap.com/docs/cli/setup#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.
