@appetize/cli 0.17.0 → 0.19.0

package/skills/appetize/SKILL.md

@@ -10,7 +10,7 @@ description: >-
   or answering what is currently on screen — even if Appetize is not mentioned
   by name.
 metadata:
-  cli-version: '0.17.0'
+  cli-version: '0.19.0'
 ---
 
 # Appetize
@@ -31,6 +31,9 @@ Confirm the CLI is installed and note the version:
 appetize --version
 ```
 
+End every command with `--json`, so its result is always JSON. If your tool runs
+commands in a terminal, add `--quiet` too.
+
 `APPETIZE_API_TOKEN` must be set for private APIs and session targets. A target
 is an uploaded build's public key, e.g. `app_a1b2c3`. Discover one with
 `appetize build list`, filtering with `--app <appId>` when you know the bundle
@@ -53,9 +56,9 @@ configured once rather than flagged on every session.
 Start a session, naming a device and a target:
 
 ```bash
-appetize session start iphone15pro app_a1b2c3
-appetize session start pixel7 app_a1b2c3 --device-os-version 14
-appetize session start iphone15pro app_a1b2c3 --open myapp://orders/42
+appetize session start iphone15pro app_a1b2c3 --json
+appetize session start pixel7 app_a1b2c3 --device-os-version 14 --json
+appetize session start iphone15pro app_a1b2c3 --open myapp://orders/42 --json
 ```
 
 This blocks until the device is ready, then prints the session:
@@ -108,7 +111,7 @@ jq 'select(.type == "response") | "\(.response.status) \(.request.method) \(.req
 Stop the session when you are done, so the device is released:
 
 ```bash
-appetize session stop
+appetize session stop --json
 ```
 
 Session state lives in `~/.appetize/cli/sessions/<session-id>/state.json` (or under
@@ -122,8 +125,8 @@ Video is not captured unless you ask for it — nothing streams from the device
 until you start:
 
 ```bash
-appetize recording start login-flow
-appetize recording stop
+appetize recording start login-flow --json
+appetize recording stop --json
 ```
 
 `recording start` has the daemon open the video stream and write it to the file
@@ -144,7 +147,7 @@ Playback is a constant 30fps, so it does not track real time.
 ### 1. Inspect first
 
 ```bash
-appetize inspect --select-test-id login-form
+appetize inspect --select-test-id login-form --json
 ```
 
 `inspect` writes the view hierarchy as JSON to `inspect.json` by default (name
@@ -164,12 +167,12 @@ not "does not exist".
 Prefer matching what an element _is_ over where it happens to sit:
 
 ```bash
-appetize tap --select-test-id save
-appetize tap --select-text 'Log in'
-appetize tap --select-text '/^item \d+/i' --select-index 2
-appetize type 'user@example.com{Tab}hunter2{Enter}'
-appetize swipe --direction up
-appetize swipe --from-test-id card-3 --to-test-id archive-bin
+appetize tap --select-test-id save --json
+appetize tap --select-text 'Log in' --json
+appetize tap --select-text '/^item \d+/i' --select-index 2 --json
+appetize type 'user@example.com{Tab}hunter2{Enter}' --json
+appetize swipe --direction up --json
+appetize swipe --from-test-id card-3 --to-test-id archive-bin --json
 ```
 
 `swipe` comes in two shapes. A `--direction` scrolls the screen (add
@@ -179,8 +182,8 @@ a target. Both ends take the same selectors as `tap`, so a drag can name its
 endpoints instead of guessing coordinates:
 
 ```bash
-appetize swipe --direction left --from-test-id card --from-index 1
-appetize swipe --from-text 'Drag me' --from-y 0.9 --to-test-id drop-zone
+appetize swipe --direction left --from-test-id card --from-index 1 --json
+appetize swipe --from-text 'Drag me' --from-y 0.9 --to-test-id drop-zone --json
 ```
 
 `--select-test-id` is the most durable, then `--select-text` (an exact string,
@@ -195,7 +198,7 @@ In `type`, `{...}` names a key: `{Enter}`, `{Tab}`, `{Backspace}`, the arrows.
 ### 3. Verify
 
 ```bash
-appetize screenshot after-login
+appetize screenshot after-login --json
 ```
 
 Screenshot after each meaningful step. A tap that "succeeded" only means the
@@ -206,7 +209,7 @@ for you.
 ### 4. Wait by inspecting, not by sleeping
 
 ```bash
-appetize inspect --select-test-id home-feed --timeout 5000
+appetize inspect --select-test-id home-feed --timeout 5000 --json
 ```
 
 `--timeout <ms>` makes the command wait for the element and fail with a non-zero
@@ -236,8 +239,8 @@ workflow, push your change so it runs, then restart the session against the
 build id it produced:
 
 ```bash
-appetize session stop
-appetize session start iphone15pro <new-id>
+appetize session stop --json
+appetize session start iphone15pro <new-id> --json
 ```
 
 If you cannot tell from the repository's CI configuration how an iOS build
@@ -257,9 +260,9 @@ When a turn ends with a visual change or a final state that deserves a demo,
 record the flow and surface the video the same way:
 
 ```bash
-appetize recording start demo
+appetize recording start demo --json
 # drive the flow
-appetize recording stop
+appetize recording stop --json
 ```
 
 Where your environment lets you attach media to a pull request, include the
@@ -276,10 +279,8 @@ transcript is the record — never commit screenshots or recordings to the repo.
 | Element not found                                | Re-inspect. It is off screen, covered, or the screen changed. |
 | App fails only on network calls                  | If you started with `--proxy`, retry without it.              |
 
-A session moves through phases while starting: `requesting`, `queued`,
-`starting`, `downloadingApp`, `installingApp`, `launchingApp`, `ready`. If
-`session start` is taking a while, that sequence tells you whether you are
-queued for capacity or waiting on an install.
+If `session start` is taking a while, `state.phase` in its `state.json` tells
+you whether you are queued for capacity or waiting on an install.
 
 ## Dismissing the soft keyboard
 
@@ -290,14 +291,14 @@ if the app wired that up, and many apps do not.
 **iOS** — press the return key:
 
 ```bash
-appetize type '{Enter}'
+appetize type '{Enter}' --json
 ```
 
 **Android** — press the back button; while the keyboard is up it dismisses
 the keyboard instead of navigating back:
 
 ```bash
-appetize press back
+appetize press back --json
 ```
 
 Both leave you on the same screen with the field still focused. Confirm from
@@ -315,15 +316,20 @@ test id or a dismiss button changes the thing you are supposed to be verifying.
 Prefer `open` over navigating screen by screen when a deep link exists:
 
 ```bash
-appetize open myapp://orders/42
-appetize open https://myapp.com/orders/42
-appetize inspect --select-test-id order-42 --timeout 5000
+appetize open myapp://orders/42 --json
+appetize open https://myapp.com/orders/42 --json
+appetize inspect --select-test-id order-42 --timeout 5000 --json
 ```
 
 `open` returning only means the URL was delivered, so verify the destination
 screen with `inspect --timeout`. A custom scheme needs its app installed on the
 device. iOS caps URLs at 2048 characters.
 
+## Logged-out state
+
+On iOS, `appetize keychain clear` clears the entire keychain without restarting
+the session. It has no effect on Android.
+
 ## Full command reference
 
 `references/commands.md` has every command, flag, output shape and exit

package/skills/appetize/references/commands.md

@@ -16,6 +16,7 @@ same flags at the terminal.
 - [press](#press)
 - [rotate](#rotate)
 - [open](#open)
+- [keychain clear](#keychain-clear)
 - [screenshot](#screenshot)
 - [recording start](#recording-start)
 - [recording stop](#recording-stop)
@@ -26,6 +27,11 @@ same flags at the terminal.
 
 ## Global
 
+`--json` prints the result as JSON. End every command with it. `--no-json`
+prints text.
+
+`--quiet` hides the progress spinner shown on an interactive terminal.
+
 `--session-id <id>` is accepted by every command except those marked "Takes
 no session". On
 `session start` it names the session being created; everywhere else it picks
@@ -55,9 +61,7 @@ once the device is ready; `--no-wait` prints `{ logs, sessionId }` immediately.
 available to it: `adb connect <adbSerial>` attaches to the device until the
 session ends. `viewerUrl` opens the local browser viewer. `logs`
 carries a `device` and a `daemon` path, plus a `network` path — the JSONL capture
-of the app's traffic — when started with `--proxy` (or `--proxy intercept`). Progress phases are logged to stderr:
-`requesting`, `queued`, `starting`, `downloadingApp`, `installingApp`,
-`launchingApp`, `ready`.
+of the app's traffic — when started with `--proxy` (or `--proxy intercept`).
 
 Network traffic can be proxied or intercepted for debugging. `--proxy` (or
 `--proxy intercept`) provisions the intercepting proxy so traffic can be
@@ -75,7 +79,7 @@ and starting a session with an id already in use fails.
 appetize session stop
 ```
 
-Signals the daemon to shut down and prints `{ ended: true, sessionId }`. Reports
+Signals the daemon to shut down and prints `{ sessionId }`. Reports
 the id even if the daemon had already exited, so it is safe to call twice.
 
 ## build list
@@ -113,7 +117,7 @@ appetize build upload <file> [options]
 
 Uploads a `.apk`, `.apks`, `.zip` or `.tar.gz` and prints
 `{ created, id, platform }` on stdout, where `id` is a target `session start`
-takes. The id is also logged to stderr as soon as the upload lands.
+takes.
 
 The extension decides the platform — `.apk` and `.apks` are Android, `.zip`,
 `.tar.gz` and `.tgz` are iOS — and any other file is refused before uploading.
@@ -172,7 +176,7 @@ appetize tap [options]
 | `--select-*` | Element or position to tap — see [Selectors](#selectors) |
 | `--timeout`  | Milliseconds to wait for the element                     |
 
-Prints `{ tapped: true }`. Combining an element selector with `--select-x` /
+Prints `{}`. Combining an element selector with `--select-x` /
 `--select-y` taps a point within that element, and values outside `0-1` are
 allowed to reach just beyond its edge (e.g. `--select-x=-0.1`).
 
@@ -191,7 +195,7 @@ appetize swipe [options]
 | `--duration`  | Milliseconds the gesture travels for                   |
 | `--timeout`   | Milliseconds to wait for any `--from`/`--to` elements  |
 
-Prints `{ swiped: true }`. Two shapes are valid: a `--direction` with an
+Prints `{}`. Two shapes are valid: a `--direction` with an
 optional `--from-*` starting point, or both a `--from-*` and a `--to-*` point to
 form a path. Mixing `--direction` with `--to-*` is an error, as is `--distance`
 without `--direction`.
@@ -206,7 +210,7 @@ appetize type <text> [options]
 | --------- | ---------------------------------- |
 | `--delay` | Milliseconds to wait between steps |
 
-Prints `{ typed: true }`. Bare text is delivered as a string; `{...}` names a
+Prints `{}`. Bare text is delivered as a string; `{...}` names a
 key delivered as a keystroke. Supported keys: `ArrowDown`, `ArrowLeft`,
 `ArrowRight`, `ArrowUp`, `Backspace`, `Enter`, `Tab`. A token may carry a repeat
 count as in `{Backspace>16/}`, and `{{` types a literal `{`. An unclosed token
@@ -220,7 +224,7 @@ Typing does not focus a field — tap it first.
 appetize press <button>
 ```
 
-Prints `{ pressed: true }`. Buttons: `home` and `lock` on both platforms;
+Prints `{}`. Buttons: `home` and `lock` on both platforms;
 `back`, `menu`, `unlock`, `volumeUp` and `volumeDown` on Android only. Calling
 an Android-only button on iOS fails.
 
@@ -233,7 +237,7 @@ main page.
 appetize rotate <orientation>
 ```
 
-Prints the resulting orientation. Orientations: `portrait`, `landscapeLeft`,
+Prints `{}`. Orientations: `portrait`, `landscapeLeft`,
 `landscapeRight`, `upsideDown`.
 
 ## open
@@ -242,9 +246,18 @@ Prints the resulting orientation. Orientations: `portrait`, `landscapeLeft`,
 appetize open <url>
 ```
 
-Prints `{ opened: true }`. `<url>` is a deep link (`myapp://orders/42`) or an
+Prints `{}`. `<url>` is a deep link (`myapp://orders/42`) or an
 http(s) URL. A malformed or scheme-less value is refused.
 
+## keychain clear
+
+```
+appetize keychain clear
+```
+
+Prints `{}`. iOS only: clears the entire keychain. No effect on
+Android.
+
 ## screenshot
 
 ```
@@ -252,7 +265,7 @@ appetize screenshot [output]
 ```
 
 `output` defaults to `screenshot`, and an extension matching the image is added
-if you omit one. Writes a PNG and prints `{ bytes, mimeType, output }`.
+if you omit one. Writes a PNG and prints `{ bytes, output }`.
 
 ## recording start
 
@@ -265,7 +278,7 @@ appetize recording start <output> [options]
 | `--force` | Overwrite the file if it already exists |
 
 Asks the daemon to open the device video stream and capture it to `output`,
-printing `{ path, recording: true }`. Capture is opt-in — video is lazy
+printing `{ path }`. Capture is opt-in — video is lazy
 device-side, so nothing streams until this runs.
 
 `output` is required. `.mp4` is added if you omit an extension, any other
@@ -284,7 +297,7 @@ capture is running.
 appetize recording stop
 ```
 
-Closes the stream and the file, printing `{ path, recording: false }`. Fails
+Closes the stream and the file, printing `{ path }`. Fails
 with `No video recording in progress` when nothing is recording. Ending the
 session while recording closes the file too, noting it in `daemon.log`.
 
@@ -355,6 +368,7 @@ slider track.
 | `APPETIZE_API_TOKEN` | Authorizes private APIs and session targets    |
 | `APPETIZE_ENDPOINT`  | Appetize URL used when `--endpoint` is omitted |
 | `APPETIZE_CLI_HOME`  | Overrides the session state directory          |
+| `APPETIZE_OUTPUT`    | `json` or `text` when neither flag is passed   |
 
 Session state is written to `~/.appetize/cli/sessions/<session-id>/state.json`.
 Device logs stream as JSONL to `device.log.jsonl` beside it, and the daemon's
@@ -362,12 +376,16 @@ own output goes to `daemon.log`.
 
 ## Exit codes and output streams
 
-Commands exit `0` on success and non-zero on failure, printing the message to
-stderr. A selector `--timeout` that expires is a failure, which is what makes it
-usable as a wait.
+Commands exit `0` on success and non-zero on failure, printing
+`{ "error": { "message": "…" } }` to stderr (text on a terminal, unless
+`--json`), plus `sessionDir` (the session's
+logs and `state.json`) once a session is found, unless the command was misused.
+A selector `--timeout` that expires is a failure, which is what makes it usable
+as a wait.
 
-Machine-readable results go to stdout as JSON. Progress and errors are always
-stderr.
+Results go to stdout as JSON (text on a terminal, unless `--json`) and hold
+only what you could not know beforehand; `{}` means the command ran. stderr
+carries only errors, plus a progress spinner on an interactive terminal.
 
 Common failures:
 
@@ -375,4 +393,4 @@ Common failures:
 | --------------------------- | --------------------------------------------------------------------------------- |
 | `No active sessions`        | `session start` first; if one should be live, its `daemon.log` says why it exited |
 | `No session found for id X` | `endedReason` in the session's `state.json`                                       |
-| `Session is not ready`      | `state.phase` in `state.json` says how far it got                                 |
+| `Session is not ready`      | `state.phase` in `state.json` under `error.sessionDir` says how far it got        |