Commands
Find the command for a task, the flags it takes, and how it behaves on each platform.
For persistent defaults and project-scoped CLI settings, see Configuration.
CLI help matches your installed version. agent-device help lists the workflow and platform guides, and help <command> gives a command’s exact flags:
agent-device helpagent-device help commandsagent-device help workflowagent-device help openIf your agent runtime supports skills, install them to route agents automatically; they are optional. The CLI help topics are the reference for your installed version.
For MCP-aware clients that support direct tools, run:
agent-device mcpFor MCP client setup and what MCP does not expose, see AI agent setup.
Common options
These options are allowed by 5 or more commands, so they are documented here once: --settle, --settle-quiet <ms>, --timeout <ms>, --depth, -d <depth>, --scope, -s <scope>, --raw, --out <path>. A command’s own entry omits them and names them in its Also accepts line. The shared row is the general case: where a command’s semantics differ, that command states its own row.
| Option | What it does |
|---|---|
--settle |
After the action, wait for the UI to go quiet and return the settled diff vs the pre-action tree in the same response (best-effort; never fails the action) |
--settle-quiet <ms> |
Settle: quiet window the UI must hold to count as settled (default 500ms; 300ms when the settled tree comes from the iOS simulator snapshot bridge). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the –timeout settle deadline; a replacement from a screen the pre-action capture read as presenting nothing, such as a tab switch, gets no 1500ms confirmation and keeps the asked window |
--timeout <ms> |
Boot/Open/Prepare: startup budget covering the device boot (and runner preparation for prepare). Replay/Snapshot/Test: maximum wall-clock time for the command or attempt. With –settle: the settle-wait deadline (default 10s) |
--depth, -d <depth> |
Snapshot: limit snapshot depth |
--scope, -s <scope> |
Snapshot: scope snapshot to label/identifier |
--raw |
Snapshot: raw node output |
--out <path> |
Output path |
Exact behavior for one command: agent-device help <command>.
Output and warnings
In text mode, every command prints each response warning as a Warning: line after its own output.
get, find, clipboard, and record print those lines on stderr instead, so
value=$(agent-device get text …) captures only the value. With --json, warnings stay in
data.warnings and no Warning: line is printed.
Text that the CLI prints can name values that a device or a remote daemon chose, such as file paths and labels. So the CLI shows control characters as escapes: a C0 character other than newline and tab, DEL, or a C1 character prints as \u00NN, for example \u001b. That is a JSON escape too, so JSON the CLI prints, with or without --json, still parses back to the exact values. Newlines and tabs are kept as layout, and a newline inside one warning is folded into a space so each warning stays on one Warning: line. Colored output keeps its own color codes. Output from a tool a command wraps, and --debug diagnostics, are escaped the same way. MCP and AI SDK tool text can show these escapes too, in warnings and other values the shared formatters escape; their structured content keeps the exact values.
Navigation
agent-device bootagent-device boot --platform iosagent-device boot --platform androidagent-device boot --platform android --device Pixel_9_Pro_XL --headlessagent-device boot --platform ios --pick newestagent-device shutdown --platform iosagent-device shutdown --platform android --device Pixel_9_Pro_XLagent-device open --platform macos --surface frontmost-appagent-device open --platform macos --surface desktopagent-device close [app]agent-device backagent-device back --in-appagent-device back --systemagent-device orientation portraitagent-device orientation landscape-leftagent-device orientation autoagent-device hardware-button volume-upagent-device hardware-button volume-downagent-device hardware-button poweragent-device fold closedagent-device fold half-openagent-device fold openagent-device telephony call 5551234agent-device telephony cancel 5551234agent-device telephony sms 5551234 "Your code is 1234"agent-device device status --platform android --serial emulator-5554agent-device device release --staleagent-device daemon stop --cleanagent-device daemon status --jsonBoot and shut down:
Boot target device/simulator.
agent-device boot [--headless] [--pick newest] [--timeout <ms>]| Option | What it does |
|---|---|
--headless |
Boot: launch Android emulator without a GUI window |
--pick newest |
Boot: when several equally preferred matches are all shut down, boot one (mobile over TV, newest OS, then name) instead of failing; booted ties still fail |
Also accepts: common options: --timeout <ms>.
Supported targets: Get the device ready and boot simulators and emulators.
Exact behavior: agent-device help boot.
Shutdown target simulator/emulator.
agent-device shutdownSupported targets: Shut down a simulator or emulator.
Exact behavior: agent-device help shutdown.
bootgets the selected target ready without launching an app. It needs an active session or a device selector. You mainly need it whenopenfails because no simulator or emulator is booted.boot --pick newestboots one device when the request names none and several equally preferred devices match, all shut down. Without it,bootfails withAMBIGUOUS_MATCHand its hint names the option. Device ranking applies to ordinary selection and theAMBIGUOUS_MATCHcount as well as this option: among Apple devices of the same kind, an iPhone ranks above an iPad, then tvOS, then visionOS, then watchOS. Among the tied devices, it prefers a mobile target over a TV, then the newest OS version, then the first name in name order. Name order compares numbers by value, so iPhone 9 comes before iPhone 17, but it is not device age: with equal OS versions, iPhone 16e comes before iPhone 17. Stopped Android AVDs report no OS version, so the name decides between them. It never picks between booted devices or provider devices. The response names the device and reportsselection.reason: newest-bootable-local.- Android:
boot --platform android --device <avd-name>launches that emulator with a window; add--headlessto launch it without one. On macOS the window opens behind the focused app, which keeps focus (also whenopenboots a stopped AVD). This is best-effort: the emulator can still take focus if the focused app cannot be read, or if its window appears after the startup budget runs out. shutdownturns off the selected local Apple simulator or Android emulator. On Limrun, it deletes an instance that agent-device created or releases an attachment to an existing instance. It refuses a device used by an active session; useclose --shutdownto end that session first.--timeout <ms>onboot,open <app>, andprepare ios-runneris the startup budget for booting an iOS Simulator or Android emulator (forprepare ios-runner, shared with runner preparation). A never-booted iOS Simulator can take several minutes. When the budget runs out, the command fails witherror.details.reason: boot_timeoutand the device keeps booting, so a retry finds it further along. See Sessions.
Select a device:
--platform appleis an alias for the Apple backend (ios,tvOS,macOS). Add--target mobile|tv|desktopto--platformto choose phone/tablet, TV, or desktop targets.- A command that needs one device fails with
AMBIGUOUS_MATCHand lists the candidates when you pass no--device,--udid, or--serialand several are equally preferred, such as two booted emulators. Virtual devices are preferred over physical ones and booted over offline ones first, and commands inside a session use the session’s device.devicesstill lists everything. - Commands without
--sessionuse an implicit session scoped to your worktree and the selected platform. For named sessions,AGENT_DEVICE_SESSION, and--session-lock reject|strip, see Sessions.
Device claims and the daemon:
Inspect and recover enforced local device ownership without a daemon.
agent-device device status|release [--platform <platform>] [--udid <udid>] [--serial <serial>] [--stale]| Option | What it does |
|---|---|
--stale |
Device status: show only claims with a provably stale owner |
Exact behavior: agent-device help device.
Stop a local daemon or show the providers it registered.
agent-device daemon stop [--clean] [--state-dir <path>] | daemon status [--state-dir <path>]daemon stop
| Option | What it does |
|---|---|
--clean |
Daemon stop: remove retained runner processes and leases after stopping |
daemon status
Reads no options.
Exact behavior: agent-device help daemon.
device statuslists host-local device claims without starting or contacting a daemon;--staleshows the stale claims it hides by default (owner exited, PID reused, state directory deleted, or daemon replaced), some of whose owners may still be running. Scope it with--platformplus--udid(Apple) or--serial(Android). A claim held by another live or uncertain owner blocksopen, unless the device rebooted after the claim was taken: thenopensettles that owner’s durable resources, takes the claim, and reports the release inwarnings.device status --jsonalso reports each claimed device once, withacquirablefor whether a new session can take it now. It is an inspection, not a promise: status cannot see a reboot and runs no recovery, soopenmay decide differently.blockedBynames why a device is not acquirable.ownernames the claim’s owner when its record decodes: the holder that blocks the device or, on an acquirable device, the reclaimable dead owneropenwould settle. A daemon’s own abandoned claim is reported as blocked by that live owner, butopenthrough that same daemon may still take it. A dead or replaced owner that retains no durable resource does not block by itself.hiddenStaleClaimscounts the claim records this view hides and is not an availability signal, so readacquirable: a hidden owner whose PID was reused or whose state directory is gone, and pending resource cleanup, each still block the device.device release --stalesettles the durable resources of an owner that provably can’t release its claim (its process exited or a newer daemon replaced it), then clears the claim. Live, uncertain, PID-reused, corrupt, and deleted-state-directory claims are refused with the reason. See Sessions.- A claim conflict on
openfails withDEVICE_IN_USEand names the conflict inerror.details.reason:DEVICE_CLAIM_LIVE_OWNER(a live owner holds the device),DEVICE_CLAIM_RECOVERY_PENDING(a dead or superseded owner’s durable resources are still being settled), orDEVICE_CLAIM_OWNER_UNCERTAIN(the owner’s liveness could not be proven). Each is a pre-dispatch refusal: nothing reached the device. - A command that needs the shared local daemon starts it for its state directory when none runs;
device statusanddevice release --stalenever contact one. When the running daemon comes from another version or build, the command replaces it only if it reports no work: no request in flight, no session, no repair session and no live lease. A resumable upload still streaming and a host human-control hold that names no lease are not counted, so a replacement can end them. Otherwise the command fails withdaemon-busyand leaves the daemon alone. A daemon from a release that predates this check is never replaced, and fails withdaemon-incompatible. End a busy or older daemon deliberately withdaemon stop. Node.js clients choose this per client; see Daemon lifecycle. daemon stop --state-dir <path>stops a detached local daemon with process signals after verifying its identity. It waits up to 75 seconds for the daemon to finish its own teardown before it forces the exit.--cleanalso removes the Apple runner processes and leases that daemon retained.daemon stoprefuses a live embedded runtime withdetails.reason: daemon-owner-embeddedand a hint naming the host PID. Close it in its host process with the handle returned bystartAgentDevice(). Stop refuses live unrecognized ownership withdaemon-owner-unrecognized. Neither refusal sends a request or signal. Stop retires an embedded or unrecognized registration when its recorded host lifetime has provably exited. Without--clean, an unreadabledaemon.jsonfails withdaemon-record-unreadable.--cleanrequires proven detached ownership; embedded, unrecognized and unreadable records fail withdaemon-clean-not-detached.daemon statusshowshost-ownedorowner-not-recognized. See Daemon lifecycle.daemon status [--state-dir <path>] [--json]reads the daemon’s record without contacting it. For a running daemon it lists every provider it registered, built in or installed, and the reason any plugin failed to register. See provider plugins.- A
--state-dirorAGENT_DEVICE_STATE_DIRyou pass to these commands must be a private directory of your own account, because the daemon’s record, lock, log, and recordings live in it. agent-device checks it before it reads anything and refuses one another account owns or can write, with the step that ends the refusal in the error. See Supported environment variables.
Open apps and links:
Open an app, deep link or URL, save replays.
agent-device open [appOrUrl] [url] [--activity <component>] [--launch-console <path>] [--launch-args <arg>] [--test-ime] [--no-test-ime] [--save-script [path]] [--force, --overwrite] [--no-record] [--relaunch] [--foreground] [--timeout <ms>] [--wait <ms>] [--surface app|frontmost-app|desktop|menubar] [--metro-host <host>] [--metro-port <port>] [--bundle-url <url>] [--launch-url <url>] [--os <version|range>] [--image-tag <tag>] [--device-mode <slim|full>] [--device-baseline <name>] [--physical]Aliases: launch, relaunch.
| Option | What it does |
|---|---|
--force, --overwrite |
Force replacement of existing state (connect: replace an active connection; –save-script: overwrite an existing target instead of refusing) |
--os <version|range> |
Proxy lease: OS version or range the backend picks the device by (Android: API level); refused without such a backend |
--image-tag <tag> |
Proxy lease: Android system image tag the backend picks the device by; refused without such a backend |
--device-mode <slim|full> |
Proxy lease: iOS simulator mode (slim or full) the backend leases; refused without such a backend |
--device-baseline <name> |
Proxy lease: saved device state (baseline) the backend restores on the leased device; refused without such a backend |
--physical |
Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend |
--surface app|frontmost-app|desktop|menubar |
macOS session surface for open (defaults to app) |
--metro-host <host> |
Session-scoped Metro/debug host hint |
--metro-port <port> |
Session-scoped Metro/debug port hint; on an emulator/simulator the host defaults to the loopback alias, physical devices still need –metro-host |
--bundle-url <url> |
Session-scoped bundle URL hint |
--launch-url <url> |
Session-scoped deep link / launch URL hint |
--test-ime |
open/test/replay: activate the headless Android test IME for deterministic Unicode text entry (default on for emulators; opt-in on real devices; on test/replay it applies to the sessions the flow opens) |
--no-test-ime |
open/test/replay: keep the real Android keyboard even on emulators (opt out of the headless test IME; on test/replay it applies to the sessions the flow opens) |
--activity <component> |
Android launch activity (package/Class, .Class, or Class) or HarmonyOS ability name; not for URL opens |
--launch-console <path> |
open: capture the initial local or Limrun iOS simulator launch console window to a file |
--launch-args <arg> |
open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args). Linux and macOS reject the flag. |
--no-post-gesture-stabilization |
Scroll, swipe, gesture swipe, open: skip the movement check and the stabilization wait that follow a gesture, and on a local iOS simulator the first-screen wait after an app launch; use it only when your own polling verifies the screen |
--save-script [path] |
Arm evidence capture on open, publish the armed recording on close; close –save-script alone (without an armed open) is rejected — start with open –save-script, or use session save-script mid-session. Optional custom output path. On Windows, absolute paths need a drive letter or ordinary UNC share. |
--relaunch |
open: terminate app process before launching it |
--foreground |
open: keep normal app/device selection and return an initial snapshot of the first screen (a local iOS simulator waits up to 10s for it); without an app, resolve the sole running app on the sole booted iOS simulator |
--no-record |
Do not record this action |
--wait <ms> |
Open: wait up to n ms for a device another session is holding before failing with DEVICE_IN_USE |
Also accepts: common options: --timeout <ms>.
Supported targets: Open and close apps, URLs, and deep links.
Exact behavior: agent-device help open.
Close an app or end the session.
agent-device close [app] [--save-script [path]] [--force, --overwrite] [--shutdown]| Option | What it does |
|---|---|
--force, --overwrite |
Force replacement of existing state (connect: replace an active connection; –save-script: overwrite an existing target instead of refusing) |
--save-script [path] |
Arm evidence capture on open, publish the armed recording on close; close –save-script alone (without an armed open) is rejected — start with open –save-script, or use session save-script mid-session. Optional custom output path. On Windows, absolute paths need a drive letter or ordinary UNC share. |
--shutdown |
close: shutdown associated simulator/emulator after ending session |
Supported targets: Open and close apps, URLs, and deep links.
Exact behavior: agent-device help close.
open [app|url] [url]boots the selected device when needed and opens the target in a session.open <url>opens deep links on Android and iOS, andopen <app> <url>opens a deep link in that app on iOS. See Desktop targets for macOS activation behavior.- Remote daemons refuse
file:URLs inopentargets and launch URLs with reasonREMOTE_HOST_INPUT_DENIED. Serve local web content over HTTP(S) instead. - On iOS devices,
http(s)://URLs open in Safari when no app is active. Custom-scheme URLs need an active app in the session. - Local iOS simulator: after
openlaunches an app and the backend reports that launch (local iOS simulators do; other devices and backends skip the wait, so their first capture can still show a launch screen), the first capture in the session polls for the app’s first screen for up to 10 seconds. A capture that starts before the 10 seconds end still completes and is judged. This includes the initial snapshot ofopen <app> --foreground. A tree counts as the first screen when, besides the app root, it shows a labeled element that is not text, such as a button, or two different texts, and two reads in a row agree. An unlabeled splash image, an empty view, a busy indicator, or a single status line such as Expo’s “Bundling 91%…” does not count, however long it stays unchanged. An app whose first screen is a single line of text, or has no labeled element at all, such as a game canvas, waits the full 10 seconds; to skip the wait, pass--no-post-gesture-stabilizationtoopen(see Scroll for the other ways to set it) and poll the screen yourself. If the wait runs out, the snapshot returns what it read with a warning:postGestureOutcome.kind: "loading"when it still showed no first screen, or"unsettled"when a first screen was there but kept changing. Runsnapshot -iagain, orwait text <expected>, before you act on it. open <app> --wait <ms>waits up to that budget for a device another session holds, then fails withDEVICE_IN_USE. The wait extends the command’s timeout, so you don’t need a longer--timeout. A claim held by another workspace’s daemon is not waited for;openreturns its recovery command at once. Device-mutating commands likeinstallandreinstallnever wait either: a claim held by another session fails them at once, and when the caller sends a workspace, another workspace’s claim under the same session name fails too. See Sessions.open <app> --launch-console <path>captures launch-time stdout/stderr for iOS simulator app launches, including Limrun. It is not valid for URL opens or other targets.open --platform macos --surface app|frontmost-app|desktop|menubarselects the macOS session surface;appis the default when you name an app. See Desktop targets.--save-scriptrecords the surface soreplayreopens it; with no surface given, replay opens an app session.- iOS simulators:
openprepares app accessibility before launching an app or URL. If an already-running app has an empty accessibility tree after an earlier XCTest session, runopen <app> --relaunch, thensnapshot -i. Preparation failures are logged and do not block launch. Runner cleanup also restores app accessibility after confirmed termination; a runner started by a release before this change is not restored, so relaunch the app withopen <app> --relaunch. - Android React Native:
open --relaunchneeds an installed package name. Install or reinstall the APK first;open <apk|aab> --relaunchis rejected. For Metro-backed JS changes, runmetro reloadbefore reaching foropen <app> --relaunch. - Android (adb): an intent target such as
open settingsrecords the package that opened asappBundleId.open settings --relaunchstops and restarts that app. If the intent matches more than one activity,--relaunchfails. - Android (ADB):
closeforce-stops the app, then checks for 2 seconds that it has left the foreground, waits up to 10 seconds for the processes it killed to exit, and checks for 2 more that no new process started. If a check window ends first,closefails withdetails.reason: android-app-close-timeoutanddetails.phaseset toforeground,exit, orprocess; a process that survives the force-stop fails withexit, and apps Android restarts at once, such as the launcher, fail withprocess.open --relaunchruns the same checks but accepts a new process once the killed ones exit, because Android can restart an app at once for a background client, such as Settings on Android 17. Whenpidofcannot list the app’s processes,closefails withdetails.reason: android-process-probe-unavailable; if that happens before the force-stop, the app keeps running. - When
closecannot confirm its cleanup on a session that holds a device claim, it fails and keeps the session and its claim, so the device is not handed on unconfirmed. Runcloseagain with the same options to retry the cleanup and release the device, leaving out--save-scriptonce the first attempt has published the script. Onlyclose, or a successfulopen, is supported on the kept session: other commands work, but the session stays marked, so an idle daemon can still shut it down. If nobody retries, the kept session does not keep the daemon alive: when the daemon has been idle for its idle timeout and shuts down, its shutdown retries the cleanup, and a claim it still cannot confirm goes stale instead of being released. Embedded runtimes andAGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS=0never shut down for idleness, so there a retriedcloseis the only release. - If
open --relaunchleaves an existing session’s device effects unconfirmed, the session and claim remain available forclose, but idle shutdown can retry cleanup and leave an unconfirmed claim stale; embedded runtimes andAGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS=0do not shut down for idleness, so usecloseto release the claim.
iOS Simulator launch behavior:
- An
openthat launches an app reportstiming.postOpenObservation. Whenever it is present, and unless theopenpassed--no-post-gesture-stabilization, the next command that reads the screen waits for the app’s first screen, up to the 10-second polling budget described underopen, so aclicklands on the real first screen where its element comes to rest. If the wait runs out, the command proceeds and warns withpostGestureOutcome.kind"loading"(no first screen yet) or"unsettled"(a first screen that kept changing). - If CoreSimulator never answers a URL hand-off,
openfails within 20 seconds withdetails.reason: ios-simulator-openurl-timeout. The Simulator may still have received the URL; retry the open or answer the prompt withalert accept. - When
open <app> --launch-url <url>raises anOpen in "<App>"?prompt and the URL’s scheme belongs to the session app,opentaps Open and returnslaunchConfirmation: "accepted". If the app still never starts,openhands over the URL once more. - On a local iOS Simulator,
openrecognizes the prompt in the Simulator’s preferred languages, through the OS’s own wording of its title and buttons, so a French Simulator’sOuvrir dans « <App> » ?is answered like the English one.alert acceptandalert dismissanswer it by the same wording. If the runner cannot read that wording, the prompt is not recognized. - When that prompt stays unanswered,
openreturnslaunchConfirmation: "unanswered"withlaunchConfirmationReason:alert-unrecognizedfor a prompt it did not recognize, orurl-owner-unresolvedwhen no single installed app owns the URL’s scheme or that lookup failed. The prompt stays on screen;warningsname the next step. Forurl-owner-unresolved, answer the prompt withalert accept. Foralert-unrecognized, read the alert withalert getfirst: it can be the app’s own alert, such as a permission prompt, rather than the launch confirmation. Answer withalert acceptonly when it is the launch confirmation. - When
opencould not read whether a prompt is up at all (the alert read, the accept, or the runner itself failed),opensucceeds withlaunchConfirmationProbeFailureset toalert-read,alert-accept, orrunnerand nolaunchConfirmation, plus a warning to check withalert getbefore retrying. details.reason: launch_confirmation_unansweredmeans the app never started after the prompt was accepted, or the prompt stayed visible after a failed tap. Answer it withalert acceptoralert dismissbefore continuing.- When the runner reports its main-thread timeout for that tap and the prompt is still up,
opentapsOpenagain, but only when the time theopenrequest has left covers a whole tap and the read that checks it. The first tap is always sent. details.reason: launch_confirmation_foreign_appmeans another installed app owns the scheme (details.foreignAppBundleId). Close the prompt withalert dismissand pass a URL your app handles.- A prompt that appears after
openhas already seen the app is not reported and not answered; usealert accept.
Back, orientation, and hardware buttons:
Navigate back in the app or system.
agent-device back [--in-app|--system] [--settle]| Option | What it does |
|---|---|
--in-app |
Back: use app-provided back UI when available; on iOS, the one hittable navigation bar back button, confirmed by a bar change, else the verified left-edge back swipe |
--system |
Back: use system back input or gesture when available; on iOS, the same back as –in-app |
Also accepts: common options: --settle, --settle-quiet <ms>, --timeout <ms>.
Supported targets: Back.
Exact behavior: agent-device help back.
Go to the device home screen.
agent-device homeSupported targets: Home.
Exact behavior: agent-device help home.
Open the device app switcher.
agent-device app-switcherSupported targets: App switcher.
Exact behavior: agent-device help app-switcher.
Set device orientation.
agent-device orientation <portrait|portrait-upside-down|landscape-left|landscape-right|auto>Supported targets: Set screen orientation.
Exact behavior: agent-device help orientation.
Press the iPhone, iPad, or Apple Watch Ultra Action Button.
agent-device action-buttonSupported targets: iPhone Action Button.
Exact behavior: agent-device help action-button.
Shake an iOS simulator or Android emulator.
agent-device shakeSupported targets: Shake.
Exact behavior: agent-device help shake.
Press a phone hardware button once.
agent-device hardware-button <volume-up|volume-down|power|mute|sleep|wake|media-play-pause|media-next|media-previous|media-rewind|media-fast-forward>Supported targets: Phone hardware buttons.
Exact behavior: agent-device help hardware-button.
backuses app-owned back navigation: the back keyevent on Android, the visible back control on macOS, and the Siri Remote Menu button on tvOS.--in-appnames this default explicitly. macOS finds that control by the app’s own back identifier or “Back” label; an app that exposes neither refuses witherror.details.reason: in_app_back_control_unavailableunderCOMMAND_FAILEDanddispatched: no, pressing nothing, so press the app’s visible back control by its ref.- iOS has no system back. On iOS,
backonly pops the navigation stack, by the back button or the edge swipe below. It does not dismiss a modal or a sheet: press that screen’s own Close or Cancel control. Android’s system back is different: it also closes dialogs and modal screens. - On iOS,
backfirst looks for the navigation bar’s system back button (a button with the identifierBackButtoninside a navigation bar, or, when none is, one floating below it, such as on the iPhone Duo). It presses that button only when exactly one live, hittable one is found, the app’s accessibility tree is readable (it is not read when XCTest could not query it earlier in the session), and the bar state has held still, so a screen that is still being pushed is not taken for the screen to go back from. It succeeds once one of these changes after the tap: the number of navigation bars, the number of back buttons (for example, the button is gone at the root screen), or a back button’s title. A back button with no title of its own, such as the Duo’s floating one, is confirmed by its navigation bar’s title instead; when no bar has a title, or a title keeps changing, that button is not pressed andbackswipes. If none changes, it reportsback_swipe_unverifiedand does not swipe. For a back button that has its own title, a bar’s title never counts, because a title can update itself, such as a countdown timer. A back button that only moves never counts either, because a tap that goes nowhere can still move it, such as when a large title collapses. So a pop that leaves the back button as it was, for example between two screens whose back buttons show the same title (such as an app that titles every back button “Back”), also reportsback_swipe_unverified. A back button whose own title updates itself, or a navigation bar that retitles itself under a back button with no title, can still be misread as a navigation. When an XCTest query hangs,backsends nothing more: before the tap it reportsback_swipe_not_dispatched, and after the tapback_swipe_unverified. Only the system back button counts: a custom bar button titled “Back”, or a “Back” button in a toolbar, is never pressed. With no such button, with two or more (such as a sheet over a stack), when the tree cannot be read, when the bar state does not hold still, or when the tap is refused before it is sent,backis the left-edge back swipe, with or without--in-appor--system. When XCTest cannot resolve the app’s window, the swipe samples the device’s only screen: on a single-screen iPhone, or on an iPad only while the app provably fills its screen; otherwise it refuses withAPP_SCREEN_UNRESOLVED. The swipe succeeds only when the app’s screen changes after it; a small spinner may not count as a change, while a larger animation can. Before it swipes,backwaits for the screen to stop changing; a screen that repaints on its own never settles, andbackreportsback_swipe_unverified. A screen that changes on its own right around the swipe can be misread as a back navigation; verify withsnapshotwhen the screen has auto-advancing content. reason: back_swipe_no_change: the swipe was sent and the screen did not change.details.dismissControlsthen lists the controls that can leave the screen: the hittable buttons in the top band of the app window whose label or identifier is Back, Close, Cancel, or anxmarkicon name, in any letter case. Done, Save, and other labels are never listed. Each entry is{ selector, label, identifier? }. Press one with its selector, for exampleagent-device press 'role=button label="Close"'; no new snapshot is needed. The selector isrole=button label="…"when the label is the dismiss word, androle=button id="…"when only the identifier is. Only controls in the app window thatbackswiped are listed. A control whose label or identifier another button in any of the app’s windows shares (compared without letter case or extra spaces) is not listed, because its selector would match both.backcannot return refs, because it expires the snapshot’s refs before it swipes. When there is exactly one control, the hint names it. The field is absent when there is no control, when the app’s tree cannot be read, or when the read fails or hangs.backnever presses these controls itself, because Close or Cancel can discard a draft or end a flow.reason: back_swipe_unverified: the back button was pressed but the navigation bar’s back buttons (or, for a back button with no title, the bar’s title) did not change after the tap or an XCTest query hung after it, or the swipe may or may not have navigated, because the screen kept changing before the swipe, the swipe took longer than the screen had been still, or the screen could not be sampled after it. Check withsnapshot. A real pop on a stack of three or more screens also answers this when the outgoing and incoming back buttons share a label.reason: back_swipe_not_dispatched: the swipe was refused before any touch went down, or an XCTest query hung before the back button tap, so nothing reached the device.- If the app’s screen cannot be captured before the swipe,
backdoes not swipe: it refuses withCOMMAND_FAILEDanddetails.runnerErrorCodeset toAPP_SCREEN_WINDOW_UNRESOLVED,APP_SCREEN_UNRESOLVED,APP_SCREEN_CAPTURE_UNRENDERABLE, orAPP_SCREEN_OFF_LIT_PANEL. Nothing is sent. - A simulator sends the swipe as a screen-edge touch. A physical device has no such touch and sends a quick fling from the leading edge instead; if that fling does not pop the screen,
backrefuses withback_swipe_no_change. visionOS has no back command and refuses before dispatch withUNSUPPORTED_OPERATION. - An app with a left-edge drawer may open the drawer instead of going back. When a custom back or close control is visible, press it by its ref.
back --systemsends system back input: the Android back keyevent, the same iOS back as the default, or the tvOS Siri Remote Menu button. macOS has no system back, so it refuses before dispatch.orientation portrait|portrait-upside-down|landscape-left|landscape-rightworks on iOS and Android mobile targets only. On ADB-backed Android it turns auto-rotate off, and the lock persists after the session ends until something turns it back on. In both default and scoped simulator sets, an iPhone Duo classified with more than one integrated panel refusesportrait-upside-downand rotates through the fold helper. It succeeds only when the lit panel shows the requested orientation; if it never does, or the simulator never reports a single lit panel, the command fails withorientation-unverified. An unresolved final guest read reportsorientation-panel-table-unavailable. A simulator classified with one panel, or whose first classification read is unresolved, uses the standard runner rotation.orientation autohands rotation back to the sensor on ADB-backed Android, local or Limrun (accelerometer_rotation=1,user_rotationuntouched), and reportsorientation: "auto". It does not wait for the display to rotate, because there is no target rotation: the sensor decides, and an emulator usually settles on portrait. Every other backend refusesautowithUNSUPPORTED_OPERATION.action-buttonpresses the iPhone or iPad Action Button once. It takes no arguments, no hold duration, and no--settle, and it doesn’t activate the session app or drive Camera Control. Other platforms refuse it, and a model without the button (an iPhone SE, most iPad simulators) fails withUNSUPPORTED_OPERATIONanderror.details.reason: hardware_control_unavailablewithdispatched: no— nothing was pressed.action-buttonreports that the press was dispatched, not what it triggered. Simulators run no Shortcuts or App Intents, so verify the outcome on a physical iPhone. Expect a press to take about five seconds on a Simulator.shakeshakes an iPhone or iPad simulator or an Android emulator once. It takes no arguments and no--settle, and it doesn’t activate the session app.- On iOS,
shakeposts the notification that Device > Shake in the Simulator app posts (simctl spawn <udid> notifyutil -p com.apple.UIKit.SimulatorShake), which UIKit delivers to the app as a motion-shake event. It injects no accelerometer data, so an app that detects shakes through CoreMotion does not see it. - On Android,
shakeoverrides the emulator’s accelerometer through the emulator console (adb emu sensor set acceleration): ten swings of about 2 g in alternating directions along the screen’s X axis, at least 80 ms apart and about a second in total, then the reading it found. An app that counts eight direction changes above 1.33 g within three seconds sees one shake. It is verified through the local adb executor only. shakereports that the shake was sent, not what the app did with it; take a snapshot afterwards. Physical devices, Android TV, remote provider devices (Limrun, Revyl, WebDriver), and every other platform refuse it withUNSUPPORTED_OPERATION.- An Android shake that fails reports
COMMAND_FAILEDwith one of two reasons inerror.details.reason.shake-rest-acceleration-unreadablemeans the console returned no accelerometer reading to restore afterwards, so nothing was sent (dispatched: no).shake-console-refusedmeans the console refused an accelerometer command, andconsoleReasoncarries its reply. When the refusal is on the initial read,dispatched: nois set and nothing changed. After a refused swing, a restore of the starting reading is attempted but not confirmed, so readadb emu sensor get accelerationbefore relying on the emulator being at rest. hardware-button <button>presses one phone hardware key once, with no hold and no--settle, and it doesn’t activate the session app. The names arevolume-up,volume-down,power,mute,sleep,wake,media-play-pause,media-next,media-previous,media-rewind, andmedia-fast-forward. The response reports the dispatched press, not what the OS did with it: which audio stream a volume press moves, which media session a media key reaches, and whether the HUD shows is device behavior the command does not claim.- Android presses all eleven keys on phones and tablets: the ADB-backed and helper paths send
input keyevent, and an Appium-backed device presses the same keycodes through itsmobile: pressKeyroute. A physical iPhone or iPad presses volume only, through the local runner or Appium’s volume button press; no Apple leaf presses the other keys. iOS Simulators refuse volume (XCUIDeviceexposes no volume press there) witherror.details.reason: unsupported-device-kindanddispatched: no, and Android TV and tvOS targets refuse with a pointer totv-remote. - A
powerpress toggles the Android screen.sleepturns it off andwaketurns it on without toggling, so wake the screen withhardware-button wakeafter a press that turned it off. After a press that turns the screen off, later commands may hit a locked screen.
Fold a foldable device:
Fold or unfold a foldable iPhone simulator or Android emulator.
agent-device fold [closed|half-open|open] [--keyframes <json>]| Option | What it does |
|---|---|
--keyframes <json> |
Fold: timed {atMs, angle} keyframes; final atMs is motion duration (up to 60000ms) |
Supported targets: Foldable pose.
Exact behavior: agent-device help fold.
fold closed|half-open|opensets the pose of a foldable iPhone simulator (iPhone Duo) or a foldable Android emulator (pixel_9_pro_fold,pixel_10_pro_fold,7.6in Foldable) and reports the pose only after confirming it on the device. Re-snapshot after every fold, even an interrupted one; refs and coordinates from before it are stale. On iOS, expect 2–4 seconds once the helper is built;half-openis reported once agreeing hinge reads confirm it. The first fold on a host or Xcode also compiles the helper and takes longer.- The iOS response names the lit panel and its size, marked
coordinateSpace: "native-panel". That size is not the next snapshot’s viewport and cannot place a tap. - iOS only:
--keyframesplays a timed trajectory instead of a preset, for examplefold --keyframes '[{"atMs":0,"angle":0},{"atMs":1667,"angle":160},{"atMs":3333,"angle":100},{"atMs":5000,"angle":180}]'. Use 2–64 keyframes starting at 0ms, strictly increasing integer timestamps up to 60,000ms, and angles from 0 to 180°. - iOS needs an Xcode with the iOS simulator SDK and foldable HID support (verified on Xcode 27.1); Device Hub and Accessibility permission aren’t required. The first fold builds a helper cached under
~/.agent-device/fold-helper, which also reads the hinge back. Build and dispatch failures reportfold-helper-build-failedorfold-hid-dispatch-failed; readback outcomes are listed below. COMMAND_FAILEDwithreason: fold-pose-unverifiedmeans the hinge reports another pose;fold-pose-unsettledmeans it reachedhalf-openbut never came to rest;fold-pose-dispatched-unverifiedmeans the pose was sent but the first hinge-angle read returned no sample, so check the lit panel with a screenshot;hingeReadFailureholds the read’s own failure.UNSUPPORTED_OPERATIONcovers single-panel devices (single-panel-deviceon Android). Physical devices are refused. An iOS simulator in a scoped--ios-simulator-device-setfolds the same way as one in the default set.- On Android,
foldconfirms the pose from the device state the emulator commits and reportshingeAngleDegreesas the hinge sensor reads it. That reading can differ from the AVD profile’s per-posture angles, such as 0°, 90°, and 180° on the Pixel folds or 15°, 90°, and 165° on the generic 7.6in Foldable. It also dismisses the lock screen that folding to the cover display can raise. For panels, poses, and timings, seeagent-device help foldable.
Simulate an incoming call or SMS:
Simulate an incoming call or SMS on an Android emulator over adb.
agent-device telephony call|accept|cancel <number> | telephony sms <number> <text>Supported targets: Call and SMS simulation.
Exact behavior: agent-device help telephony.
telephony call <number>starts an incoming call from<number>on an Android emulator;telephony accept <number>answers it andtelephony cancel <number>ends it.telephony sms <number> <text>delivers a text message from<number>. Use it to check how an app reacts when a call or message arrives, for example whether video playback pauses and resumes.- The events go through the emulator console (
adb emu gsm call|accept|cancel,adb emu sms send), so they work on Android emulators reached through the local adb executor. Other adb executors, such as an ADB provider, have not been verified. Physical Android devices refuse withUNSUPPORTED_OPERATIONandreason: unsupported-device-kind; iOS, macOS, tvOS, web, Linux, HarmonyOS, Vega, and Limrun and WebDriver (Appium) sessions refuse withUNSUPPORTED_OPERATIONtoo: agent-device sends telephony only through adb and does not drive Appium’s own call or SMS simulation. <number>is digits with an optional leading+, up to 15 digits. Quote the SMS text, or pass it as the remaining words; the text is sent as one argument, with backslashes and line breaks (LF, or CRLF sent as LF) escaped for the emulator console. Tabs, lone carriage returns, and other C0 or C1 control characters are refused.- The emulator console answers some events with an error, such as
acceptfor a number with no call. That fails withCOMMAND_FAILED,reason: telephony-console-refused, and the console’s ownconsoleReason.cancelfor a number with no call succeeds, because the console answers it withOK. - The emulator drops SMS characters outside the Basic Multilingual Plane, such as emoji, and delivers the rest of the text.
textLengthcounts the text as sent. - The call screen or message notification can cover the app. Re-snapshot before using refs from before the event.
Remote daemons and tenants:
--tenant,--session-isolation tenant,--run-id, and--lease-idenforce lease admission on tenant-scoped daemons.--daemon-base-url http(s)://host:port[/base-path]calls a remote HTTP daemon directly instead of starting a local one. Add--daemon-auth-token <token>(orAGENT_DEVICE_DAEMON_AUTH_TOKEN) for non-loopback daemon URLs.- Remote screenshots download to the path you pass. When a remote
record stoprequest leaves a destination unspecified, the client saves that file in your working directory and reports a warning. - To drive a Mac’s simulators and devices from another machine, see Remote proxy. For hosted devices in CI, see BrowserStack, AWS Device Farm, or TestMu AI. For
connect --remote-config, see Remote Metro workflow.
agent-device open "https://example.com" --platform ios # open link in web browseragent-device open MyApp "myapp://screen/to" --platform ios # open deep link to MyAppagent-device back --platform ios # navigation bar back button, else a verified left-edge swipeagent-device reinstall MyApp /path/to/app-debug.apk --platform android --serial emulator-5554agent-device open com.example.myapp --platform android --serial emulator-5554 --session my-session --relaunchagent-device metro reloadHuman Takeover
Pause agent interactions while a person controls a device.
agent-device takeover [status | release <hold-id>] [--session <name>]Exact behavior: agent-device help takeover.
Use takeover with an active remote connection when a person needs to use its leased device
without racing the agent:
agent-device takeover --session remote-sessionagent-device takeover status --session remote-sessionagent-device takeover release <hold-id> --session remote-sessiontakeover holds the device until you press Ctrl+C. While it holds, state-changing commands fail with
DEVICE_IN_USE and details.reason: "human_control_active"; read-only diagnostics still work. It
needs a device-scoped remote lease, so local sessions aren’t supported. Holds don’t survive a daemon
restart; reconnect and take the hold again. See Remote proxy.
Web Automation
Manage web automation backend.
agent-device web setup | web doctorExact behavior: agent-device help web.
--platform web drives a browser through agent-browser and requires Node 24+. Use it when a browser step belongs inside an agent-device session, replay, batch, MCP, or Node.js client flow. For standalone browser automation, use agent-browser directly.
Set up and verify the managed web backend before you open a web session:
agent-device web setupagent-device web doctoragent-device open "https://example.com" --platform webagent-device snapshot -i --platform webagent-device get text @e2 --platform webagent-device is visible 'label="Welcome"' --platform webagent-device find text "Welcome" exists --platform webagent-device click @e12 --platform webagent-device hover @e14 --settle --platform webagent-device fill @e13 "test@example.com" --platform webagent-device wait text "Welcome" --platform webagent-device network dump 25 --include headers --platform webagent-device audio probe start 10 1000 --platform webagent-device audio probe status --platform webagent-device audio probe stop --platform webagent-device screenshot ./artifacts/web-home.png --platform webagent-device screenshot ./artifacts/web-full.png --platform web --fullscreenagent-device viewport 1280 900 --platform webagent-device close --platform webweb setupinstalls a pinnedagent-browserbackend into the agent-device state directory (--state-dir,AGENT_DEVICE_STATE_DIR) and reuses it when present. Run it before first use and in CI bootstrap: web commands never install the backend themselves and use only that managed install.web doctorverifies it.- Each web session has its own browser, cookies, and storage, and holds its own device (
agent-browser-chrome:session:p_<name>, ort_<tenant hash>_<name>under tenant isolation, so two tenants never share a browser). Sessions with different--sessionnames run at once on one host. A name matches case-insensitively and must be 1 to 30 characters of letters, digits,_, and-(1 to 17 under tenant isolation); any other name, including surrounding whitespace or an empty--session "", is refused withINVALID_ARGS(web_session_name_invalid) and never falls back todefault. The same session name in the same tenant conflicts, and two daemons that share a claims directory refuse it withDEVICE_IN_USE; different tenants may reuse a name. Without--sessionunder local workspace scoping, each workspace uses its own browser and device (agent-browser-chrome:session:w_<workspace scope>). Different workspaces can run in parallel; the same workspace conflicts across daemons that share a claims directory. A request without a workspace scope, such as an RPC call without acwd, uses thedefaultsession’s browser and device (p_default, ort_<tenant hash>_defaultunder tenant isolation). - Supported: URL open, snapshot refs,
get text/attrs,is visible/hidden/exists/absent/focused/text,find text/selector, click/press, hover, fill/type, wait,network dump,audio probe, screenshot, close, and replay scripts made from those commands. - Web
fill <x> <y> <text>clicks the point and selects the clicked field’s content in the page, so it replaces or clears the text without sending a select-all key. It refuses when the click did not reach an editable text field:COMMAND_FAILEDwitherror.details.reasontext_entry_focus_not_observedanddispatched: unknown(the click happened), and no text, Backspace, Enter, or Tab is sent. Editable means a text, search, email, url, tel, password, or number input, atextarea, or a contenteditable element that is not read-only or disabled, in the page, an open shadow root, or a same-origin frame. A date, color, range, or checkbox input, aselect, a field in a cross-origin frame, a sandboxed frame withoutallow-same-origin, or a closed shadow root, and a click on non-editable content while another field stays focused, all refuse. A selector fill resolves to a point and reaches the same coordinate path, so it hits the same limits. Runsnapshot -iagain and fill the field it reports by ref, for examplefill @e2 "text"; a ref fill does not depend on the click point. hover <@ref|selector|x y>moves the pointer without pressing so hover-gated UI (row toolbars, menus) appears. Add--settleto read what it revealed; on web,--settleneeds a selector or coordinate target because web refs carry no geometry.audio probe start [durationSeconds] [bucketMs]samples HTML media elements into RMS/peak dBFS buckets; see Debugging and profiling.- Not supported: tab/window/devtools control, network routing/interception/HAR, cookies/storage, downloads/uploads, arbitrary page scripting, multi-page orchestration, and raw browser diagnostics. Use
agent-browserdirectly for those.
Device isolation scopes
agent-device devices --platform ios --ios-simulator-device-set /tmp/tenant-a/simulatorsagent-device devices --platform android --android-device-allowlist emulator-5554,device-1234--ios-simulator-device-set <path>limits simulator discovery and commands to that simulator set. iOS physical devices are not listed while it is set.- If the selected Xcode can’t resolve a scoped simulator for the Apple runner, the runner start fails with
details.reason: "simulator_set_destination_not_found", naming the set and, when known, the Xcode version. --android-device-allowlist <serials>limits Android discovery and selection to comma- or space-separated serials.- Set the same scopes with the
iosSimulatorDeviceSetandandroidDeviceAllowlistconfig keys, orAGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST. CLI flags override environment values, except under astripsession lock, which ignores conflicting per-call selectors. - Start the daemon with
AGENT_DEVICE_IOS_SIMULATOR_DEVICE_SET=<path>to scope every iOS simulator request to one simulator set. A request without--ios-simulator-device-setuses that set, so iOS physical devices are not listed on that daemon. A request naming a different path string, including the same path with a trailing slash, fails withINVALID_ARGSanddetails.reason: "ios_simulator_device_set_outside_daemon_set". macOS and other non-iOS requests ignore the set, and the host Mac stays listed. A daemon that the CLI starts inherits the CLI’s environment, so later CLI calls with a different value still use the first value until the daemon restarts. - Scope applies before
--device,--udid, and--serial, so an out-of-scope selector fails withDEVICE_NOT_FOUND. - On macOS, daemon startup removes any symlink at
~/Library/Developer/XCTestDevices, including one you made yourself (for example to move it to another volume), and restoresXCTestDevices.agent-device-backupwhen it exists. A symlinkedXCTestDevicesis not supported. Only the link is removed, never the directory it points to;daemon.logrecords each step and any failed restore, which doesn’t stop the daemon.
Device discovery
List available devices and simulators.
agent-device devicesExact behavior: agent-device help devices.
List supported commands for the selected device.
agent-device capabilitiesExact behavior: agent-device help capabilities.
agent-device devices --platform iosagent-device devices --platform androidagent-device devices --platform harmonyosagent-device devices --platform vega --target tvagent-device devices --platform ios --ios-simulator-device-set /tmp/tenant-a/simulatorsagent-device devices --platform android --android-device-allowlist emulator-5554,device-1234agent-device capabilities --platform androidagent-device capabilities --session checkout --jsondeviceslists available targets after applying--platformand isolation scopes.- Each device carries
model(such asiPhone 17 ProorPixel 9) andosVersion(such as26.1or16) when platform tooling reports them:simctlfor iOS simulators,devicectlorxctracefor physical iOS devices, andro.product.modelandro.build.version.releasefor running Android devices. Android emulators report the system image model, such assdk_gphone64_arm64. Stopped AVDs and other platforms omit both fields. They describe a device and are not selectors. open --jsonandsession list --jsonreport the attached device the same way:kind(simulator,emulator, ordevice), plusmodelandosVersionwhen the host reported them, so a CI job records the OS a run used from the command result alone. A cloud provider reportsosVersionwhen its session answer names the OS it granted, which can differ from the requested one. A target that reports no OS omitsosVersion; nothing infers one.capabilitieslists the commands the session device, or an explicit--platform/--device/--udid/--serialtarget, supports. JSON output includesdeviceandavailableCommands; useavailableCommandsinstead of keeping your own platform support table. Android also reportstargetReadiness.press: "bounded-geometry"when element presses check moving targets before dispatch. Test harnesses can use that capability to delegate tap readiness instead of adding a fixed transition delay. It does not wait for the result of the tap.
HarmonyOS command boundary
HarmonyOS support uses HDC and ArkUI uitest. On API 24 devices it supports lifecycle and HAP deployment, ArkUI snapshot/screenshot and selector reads, one-pointer touch and text actions, keyboard enter/dismiss, app logs, foreground app state, process RSS samples, and settings clear-app-state. Run agent-device capabilities --platform harmonyos for the command list of a selected device.
gesture pan|fling|swipeandswipeuse single-pointer input. Multi-touch gestures and target-authoredgesture dragreturnUNSUPPORTED_OPERATION.- Physical devices support whole-screen recording with
record start <path> --scope deviceor--scope system, without--fps,--quality, or--hide-touches. Emulator recording is rejected. - Not available: orientation, clipboard, alerts, network/audio capture, push and app-event delivery, React Native helpers, and trace capture.
settingssupports onlyclear-app-state.perf memory samplereports process RSS; frame health and memory snapshots are unavailable.
Diagnostics
Diagnose device, app, dev-server, and RN/Expo readiness.
agent-device doctor [--platform ios|android|harmonyos|vega|macos|linux|web|apple] [--app <id-or-name>] [--remote]| Option | What it does |
|---|---|
--app <id-or-name> |
Target an app without opening it: doctor verifies an installed app by id or name; settings applies an app-scoped change (permission, iOS location) to a bundle id or package |
--remote |
Doctor: check remote connection setup instead of local device inventory |
Exact behavior: agent-device help doctor.
agent-device doctoragent-device doctor --platform iosagent-device doctor --platform android --app com.example.myappagent-device doctor --remote --jsondoctordiagnoses device, app, Metro, and React Native setup for the selected target. It is read-only: it never boots, installs, or changes the device.--platform ios|android|vega|macos|linux|web|applelimits checks to one backend; without it,doctorchecks every discoverable target.--app <id-or-name>adds app checks (install state, Metro and React Native wiring) for one bundle id or app name.--remoteruns only the checks that don’t need a booted device; use it in CI bootstrap.
Prepare Apple runner
Pre-warm platform helpers before automation.
agent-device prepare ios-runner --platform ios|macos [--timeout <ms>]Also accepts: common options: --timeout <ms>.
Supported targets: Prepare the Apple runner.
Exact behavior: agent-device help prepare.
agent-device prepare ios-runner --platform ios --timeout 240000- In Apple CI setup, run
prepare ios-runnerafter the device is booted and the app is installed, before the firstsnapshot,replay, ortest. It builds or reuses the Apple runner, starts it, and checks that it answers. --timeout <ms>is one budget shared by the Simulator boot and runner preparation; see Navigation.- In JSON output,
buildMs,connectMs, andhealthCheckMsmay overlap (connectMsincludesbuildMswhen the runner is built). Usetiming.additivePartsfor additive phase totals. - A cached runner that fails its health check is rebuilt once, and a runner stuck at launch is relaunched once.
- CI may cache
~/.agent-device/apple-runner/derivedwhen the cache key includes the exact agent-device package contents and Xcode version. A cached runner whose files no longer match their recorded digests is rebuilt. - Each runner source or Xcode change creates a new key under
~/.agent-device/apple-runner/derived/<platform-folder>/. After a build, agent-device deletes, on a best-effort basis, keys that are neither among the 3 last used nor used in the last day, and never one a build is holding or a live runner lease names; change the count withAGENT_DEVICE_IOS_RUNNER_CACHE_KEEP(see Configuration). A key that can’t be deleted is reported as arunner_xctestrun_cache_eviction_failedwarning. A customAGENT_DEVICE_IOS_RUNNER_DERIVED_PATHis never swept or trimmed. runner_cache_uncertifiablemeans the build products couldn’t be verified, for example a product outside the derived-data root, an unreadable entry, a file over 128 MB, or a socket. PointAGENT_DEVICE_IOS_RUNNER_DERIVED_PATHat a plain directory you own, or replace the tree as the error hint describes.~/.agent-device/ios-runnerbelongs to older agent-device versions and is never touched. Delete it withrm -rf ~/.agent-device/ios-runneronce no such version runs.- Runner build and start output goes to the session’s
runner.log;daemon.logcovers daemon startup.
TV targets
Press a TV remote navigation, media, or hardware button.
agent-device tv-remote [press|longpress] <up|down|left|right|select|menu|home|back|volume-up|volume-down|mute|power|sleep|wake|media-play-pause|media-play|media-pause|media-stop|media-next|media-previous|media-rewind|media-fast-forward|channel-up|channel-down|last-channel|guide|info|captions|tv-input|color-red|color-green|color-yellow|color-blue|android-keycode:<n>> [--duration-ms <ms>]| Option | What it does |
|---|---|
--duration-ms <ms> |
Scroll: pace the gesture over this duration when supported |
Supported targets: TV remote keys.
Exact behavior: agent-device help tv-remote.
agent-device open YouTube --platform android --target tvagent-device apps --platform android --target tvagent-device snapshot -i --platform android --target tvagent-device tv-remote press down --platform android --target tvagent-device tv-remote press select --platform android --target tvagent-device tv-remote longpress select --platform android --target tvagent-device tv-remote press select --duration-ms 900 --platform android --target tvagent-device tv-remote volume-down --platform android --target tvagent-device tv-remote media-play-pause --platform android --target tvagent-device tv-remote android-keycode:300 --platform android --target tvagent-device screenshot tv-focus.png --overlay-refs --platform android --target tvagent-device open Settings --platform ios --target tvagent-device screenshot apple-tv.png --platform ios --target tvvega virtual-device startagent-device devices --platform vega --target tvagent-device open com.example.app.main --platform vega --target tv --session vega-tvagent-device tv-remote press down --platform vega --target tv --session vega-tvagent-device tv-remote press select --duration-ms 900 --platform vega --target tv --session vega-tvagent-device close com.example.app.main --session vega-tvvega virtual-device stop- TV targets include Apple TV and Android TV simulators, emulators, and connected devices, plus Fire TV devices and emulators running Fire OS (Android-based). Vega OS support is limited to the Vega Virtual Device (VVD).
- TV targets are focus-first: move focus with
tv-remotebefore selecting a control. Don’t use rawadb shell input keyeventin command plans. tv-remoteis TV-only. Android phones, iPhones, and WebDriver (Appium) sessions refuse it withUNSUPPORTED_OPERATION.- All three TV backends support
up,down,left,right,select,menu,home, andback. Android TV also acceptsvolume-up,volume-down,mute,power,sleep,wake,media-play-pause,media-play,media-pause,media-stop,media-next,media-previous,media-rewind,media-fast-forward,channel-up,channel-down,last-channel,guide,info,captions,tv-input,color-red,color-green,color-yellow, andcolor-blue. tvOS and Vega OS refuse the additional buttons before dispatch. - For an Android TV remote button without a name, use
android-keycode:<n>with a decimal code from 1 to 2147483647. Other TV backends refuse raw Android codes. An unknown name or invalid code fails withINVALID_ARGS. powerandsleepcan turn the screen off. A successful response confirms that the button was sent; it does not verify playback, volume, or display state, and it does not wait for the app to settle.- Android TV: app listing reads
LEANBACK_LAUNCHERandLAUNCHERactivities together; app launch prefersLEANBACK_LAUNCHERand falls back toLAUNCHERwhen the app declares no leanback activity.tv-remotesends ADB keyevents;longpress <button>selects the long-press preset, and any positive--duration-msuses Android’s longpress keyevent, which has no exact hold time. - Fire TV: a Fire TV device or emulator running Fire OS connects as an Android TV device over ADB. On the device, enable ADB debugging in Settings > My Fire TV > Developer options, then
adb connect <device-ip>:5555and use--platform android --target tv. Discovery reads theamazon.hardware.fire_tvsystem feature, so a Fire TV that declares no leanback feature is still detected as a TV target and runs the Android TV backend. The Android snapshot helper requires Android 6.0 (API 23) or newer. - tvOS supports the same runner-driven commands as iOS (
snapshot,wait,press,fill,get,scroll,back,home,app-switcher,record, and selector flows).backis the Siri Remote Menu button,homeis Home, and the app switcher is a double Home press;--duration-msis an exact hold. Helpers that are simulator-only on iOS, such assettingsandpush, are simulator-only on tvOS too. tvOS refuses multi-touch gestures such asgesture pinch. - Vega OS: use
--platform vega --target tvwith Vega component IDs such ascom.example.app.main, and--serial VirtualDeviceto select the VVD explicitly. Commands go through the SDK-matched Vega CLI and VDA. The VVD supports app open/close,back,home, and the eight navigation buttons listed above, with exact holds. - Some Fire TV devices ship with Vega OS instead of Fire OS. Vega OS is a different OS and is supported only in the Vega Virtual Device: app inventory, snapshot, screenshot, selectors, install, touch/text/gesture, logs, and performance report unsupported for Vega targets, and physical Vega OS devices are not supported. Use the VVD display as visual truth.
- LG webOS TVs run through the optional
@agent-device/webosplugin, which drives web apps over the Chrome DevTools Protocol. See LG webOS. - Samsung Tizen TVs run through the optional
@agent-device/tizenplugin, which drives web apps over the Chrome DevTools Protocol. See Samsung Tizen. - On Android TV and tvOS, use
screenshot --overlay-refsfor visual focus evidence, especially when focus metadata is missing or transient.
watchOS simulators
Apple Watch simulators use the same XCUITest runner as iOS. Select one with --platform ios and its --udid or --device name; a watch is never picked when another Apple simulator matches.
agent-device open com.apple.NanoSettings --platform ios --device "Apple Watch Series 11 (46mm)" --session watchagent-device snapshot -i --session watchagent-device press 'label="Smart Stack"' --session watch --settleagent-device scroll down --session watchagent-device swipe 180 124 20 124 --session watchagent-device back --session watchagent-device close --session watch --shutdown- Simulators only. Device discovery does not list a physical Apple Watch. The host needs the watchOS simulator runtime:
xcodebuild -downloadPlatform watchOS. scroll up|downturns the Digital Crown. The amount is a fraction of the screen height, soscroll down 1moves about one screen. The crown also moves pickers and steppers that have crown focus.scroll left|rightis refused; swipe instead.swipeandgesture swipe|pan|flingsend one-finger touches to the session app: horizontal and vertical pages, row swipe actions, and pan in custom views.gesture swipe right-edge(from the left edge toward the right) goes back.- Commands act on the session app and bring it back to the foreground first, except the hardware presses
homeandaction-button, which act on whatever is on screen. The watch face and its overlays, such as Notification Center and the Smart Stack, are not reachable. backpresses the navigation bar back button and waits up to 1 s for the navigation bar to change; if it does not,backfails withback_swipe_unverified(dispatched: unknown). A screen without a back button, such as a root screen, refuses withback_swipe_not_dispatched(dispatched: no): watchOS pops by edge swipe only while that button is shown. Press the screen’s close control by ref instead.homepresses the Digital Crown. From an app it shows the watch face; from the watch face it opens the app grid.fillandtypewait for the system input sheet that a text field opens (its keyboard), type into it, press the sheet’s Done button, and wait for the sheet to close. Done is found by its English label. On another system language, or when the sheet stays open, the command fails withTEXT_INPUT_COMMIT_NOT_OBSERVEDand the text stays in the sheet; press its commit button by ref.action-buttonpresses the Action Button on Apple Watch Ultra; other models refuse withhardware_control_unavailable.open,close,install,uninstall,boot,snapshot,find,wait,is,get,press,longpress,appstate,screenshot, andrecordwork as on iOS.record startcaptures the watch screen with the host recorder (simctl recordVideo), so it needs no runner recorder and records at the watch’s own resolution.record stopexports MP4 and burns in touch overlays the same way it does on an iOS simulator.--fps,--quality,--hide-touches, and--scopebehave as on an iOS simulator.- Everything else is refused before dispatch with
reason: unsupported-platform-leaf, includingorientation,keyboard,app-switcher,clipboard,settings,alert,logs,network,perf,push,apps, and multi-touch gestures such asgesture pinch. watchOS apps have no pinch or rotate gestures, and the App Switcher opens on a crown double-click that XCUITest cannot press. - Open apps by their watch bundle ID, such as
com.apple.NanoSettings. Withoutappsthere is no name lookup, and app aliases such assettingsresolve to iPhone bundle IDs.
Desktop targets
agent-device devices --platform macosagent-device open TextEdit --platform macosagent-device open --platform macos --surface desktopagent-device snapshot -i --platform apple --target desktop--platform macos, or--platform apple --target desktop, selects the host Mac as adesktoptarget.- agent-device automates Electron and other Chromium-based macOS apps through the macOS accessibility tree. On the native backend,
snapshotturns the app’s Chromium accessibility tree on before reading it; once on, the tree stays on for the app’s lifetime, so other surfaces see it too. See the Chromium note under the native backend below. - Use an
appsession for normal app control:open,snapshot,click,fill,press,scroll,back,screenshot,record. In app sessions,screenshotcaptures the app window, not the whole desktop. - Use the other surfaces to inspect desktop-wide UI before choosing an app, mainly with
snapshot,get,is, andwait:frontmost-appis the focused app,desktopis the visible windows across the desktop, andmenubaris the active app’s menu bar and system menu extras. To click or fill inside one app afterwards, open it in anappsession. open <app> --platform macosattaches to a copy of the app that is already running, including one you started yourself from a script or supervisor. It opens that copy by its own app path, so another build registered for the same bundle ID, such as an earlier dev build at another path, does not start beside it. If that copy has not finished registering with macOS, the open waits briefly for it before handing the URL over, so a copy that registers within that window keeps the arguments it was started with; a copy still unregistered after the wait, or copies running from more than one path, get the plainopen -b, which can start a second instance.open <app> --platform macos --surface menubartargets one app’s menu bar extras. Prefer it for status-item apps, which often expose little through theappsurface.- Prefer selectors and
@refs; window positions shift between runs, so raw x/y is less stable. Useclick --button secondaryfor context menus, then runsnapshot -iagain. - On
frontmost-appandmenubar,pressandclickpost synthetic mouse events (desktopis inspect-only).--hold-mskeeps the button down (at least 40 ms, default 60 ms),--countsends independent clicks, and--double-tapsends double-click pairs. Apps like Finder read two clicks at the default interval as one double-click; pass an--interval-mslonger than the system double-click time to keep them apart. Long schedules get the time they need, and a cancelled or interrupted click releases the button.--jitter-pxis ignored on these surfaces. - macOS also supports
clipboard read|write,trigger-app-event,logs,network dump,audio probe,alert, and part ofsettings(see Settings helpers).audio probesamples host system audio and needs Screen Recording permission; see Debugging and profiling. - Mobile-only commands are unsupported on macOS:
boot,shutdown,home,orientation,app-switcher,action-button,shake,fold,install,reinstall,uninstall,install-from-source, andpush.
XCTest opens bring the named app to the front. open --surface frontmost-app takes no app target and opens the app that is already frontmost. --foreground requests an initial snapshot; it does not choose activation. Run agent-device help macos for the versioned contract.
Set AGENT_DEVICE_MACOS_APP_BACKEND=native to run macOS app sessions without XCTest. There is no Automation Mode overlay, the app can stay behind other windows, and your pointer stays yours while a drawn pointer shows each action.
With the native backend, each app you open on the app surface is a device of its own. Several agents can drive different apps of one Mac at the same time, in one daemon or in daemons that share a claims directory. Two sessions on the same app conflict. A desktop, menubar, or frontmost-app session holds the whole Mac, so it conflicts with every app session. open --wait waits for a conflicting session in the same daemon only; another daemon’s session refuses the open at once. An app session:
- Opens its app in the background, so the frontmost app stays in front.
- Opens and closes only its own app.
open <url>opens the link in that app. Use a new--sessionfor another app or surface. - Refuses
clipboard,settings, andaudio probe, which act on the whole Mac, withUNSUPPORTED_OPERATION(reason: unsupported-device-scope). Use a--surface desktopsession for them. - Cannot see UI that another process shows, such as a system permission prompt.
Copies of one app need distinct bundle ids. Screenshots run one at a time across the Mac. Use one agent-device version per claims directory.
click,press, andfilluse accessibility actions on the element at the target point, which must be inside one of the app’s on-screen windows, not its menu bar.click --button secondaryopens the context menu of the nearest element at the point that offers one (AXShowMenu); the open menu shows in the nextsnapshot, andclickon one of its items picks it. It fails withUNSUPPORTED_OPERATION(helperReason: no-context-menu) when no element there offers a menu (no-accessible-targetwhen no element is at the point). It fails withCOMMAND_FAILEDandreason: context-menu-not-observedwhen the app’s window list was readable but showed no new menu window, and withreason: window-list-unreadablewhen the window list could not be read before the action or by any read during the wait for the menu.typeinserts at the focused control or falls back to key events.scrollmoves the scroll bar under the front window’s center. Electron and other Chromium-based desktop apps expose their web content in the snapshot: the firstsnapshotturns the app’s Chromium accessibility tree on, and a snapshot warns when that tree did not populate.screenshotcaptures only the app’s front window, even when it is covered. The front window is the app’s frontmost visible, nonempty normal-level (layer-0) window on the current Space: floating palettes and app-modal alerts at window level 8 are skipped, as is the small indicator window macOS adds in front of a window that a screen-sharing stream captures, and a sheet is captured as its own window. If that window cannot be captured,screenshotfails; it never captures another window.record,prepare,back,longpress,--hold-ms,--double-tap, gestures, and clicks on an element with no accessibility action fail withUNSUPPORTED_OPERATION(reason: unsupported-device-backend). Use the default XCTest backend for those.
# One app, full interactionagent-device open TextEdit --platform macosagent-device snapshot -iagent-device fill @e3 "hello"agent-device screenshot textedit.pngagent-device close
# Desktop-global inspection firstagent-device open --platform macos --surface desktopagent-device snapshot -iagent-device is visible 'role="window" label="Notes"'agent-device screenshot desktop.pngagent-device close
# Menubar / menu-extra inspectionagent-device open --platform macos --surface menubaragent-device snapshot -iagent-device wait 'label~="Wi-Fi|Control Center|Battery"'agent-device close
# Targeted menu bar app inspectionagent-device open MenuBarApp --platform macos --surface menubaragent-device snapshot -iagent-device closeSnapshot and inspect
Capture or diff the accessibility tree.
agent-device snapshot [--diff] [-i] [--depth, -d <depth>] [--scope, -s <scope>] [--raw] [--actions] [--observe-only] [--force-full] [--timeout <ms>]| Option | What it does |
|---|---|
--diff |
Snapshot: show structural diff against the previous session baseline |
--record |
Force-record this action into a repair-armed heal; per-invocation only, the retired config key “record” no longer opts in (mutually exclusive with –no-record) |
-i |
Snapshot: interactive elements only |
--actions |
Snapshot: name the affordances merged inside an element (iOS sim); not directly invokable — reach them via the detail screen, labeled children, or coordinates |
--observe-only |
Snapshot: observe the iOS session app without activation or foreground repair |
--force-full |
Snapshot: re-emit the full tree even when unchanged |
Also accepts: common options: --timeout <ms>, --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Accessibility snapshot, snapshot diff, and audit.
Exact behavior: agent-device help snapshot.
Read element text or attributes.
agent-device get text|attrs <@ref|selector>| Option | What it does |
|---|---|
--record |
Force-record this action into a repair-armed heal; per-invocation only, the retired config key “record” no longer opts in (mutually exclusive with –no-record) |
Also accepts: common options: --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Refs, selectors, element lookup, and attribute reads.
Exact behavior: agent-device help get.
agent-device diff snapshot [-i] [-d <depth>] [-s <scope>] [--raw]agent-device get text @e1agent-device get attrs @e1--rawreturns the full provider tree, including offscreen nodes and structural wrappers. See iOS capture behavior and Android capture behavior.- Android snapshots install the bundled snapshot helper on first use; a source checkout must run
pnpm build:androidbefore Android verification. truncated: truemeans the capture hit a backend node limit and the last elements in document order are missing; see Truncated captures.viewport: { width, height }names the box node rects are measured in; see Coordinates and viewport.--scope <text|@ref>re-roots the snapshot at the first matching node; see Scope a snapshot.--actionslists custom accessibility actions an element merged away (iOS simulator only, rejected with--raw); see Snapshots.diff snapshot(aliassnapshot --diff) compares with the previous session baseline, then updates it. It compares only trees read with the same-i,-d,-s,--rawand--actions: when the stored snapshot was read in another view, the capture starts a new baseline (baselineInitialized: true) instead of listing the view change as changes.
Audit the current screen
Report advisory accessibility findings.
agent-device auditSupported targets: Accessibility snapshot, snapshot diff, and audit.
Exact behavior: agent-device help audit.
audit captures the current screen once and reports advisory accessibility findings. Findings are review prompts, not failures, and audit changes nothing on the device.
On an iOS 17+ target served by the XCTest runner, audit also runs Apple’s native checks for contrast, element detection, hit regions, sufficient element descriptions, and traits. Apple’s Dynamic Type and clipped-text checks are not run, because they resize the app’s text while they run; agent-device help accessibility describes the large text check to use for them. iOS simulators and physical devices configured with that runner are supported. Android, TV, macOS, web, and physical devices without the runner run the heuristic checks only. Before iOS 17, audit returns the heuristic findings alone. The first audit after an install or update builds the runner once, which takes longer. A runner answer the CLI cannot read fails with COMMAND_FAILED and reason native-audit-invalid-result.
A system alert over the app, such as a permission prompt, stops Apple’s checks. audit then fails with COMMAND_FAILED and reason native_audit_blocked_by_alert, and the message names the alert. Run agent-device alert accept or agent-device alert dismiss, then run audit again.
Native findings have source: "native", kind: "native", platform, auditType, Apple’s description, and rect in snapshot points when Apple supplies an element. When a frame uniquely matches a captured element, the finding includes its snapshot ref, role, and accessible name. Otherwise, match its geometry against a fresh snapshot before acting. A finding without a rect names no element: report it without acting on it. A native hitRegion finding on the frame of a small-target finding is left out, because small-target reports that control with its ref and size. Native findings are listed by check, then top to bottom and left to right, so two audits of an unchanged screen print the same list. All native issues are collected without failing the runner test. Heuristic findings keep their existing fields.
small-target: an enabled, visible control below 44pt on iOS or 48dp on Android, with a 0.5-unit tolerance for layout rounding. Android pixels convert to dp with the captured display density; without it the check reports a limitation instead. TV and desktop targets skip the check. A link inside a text container is exempt.missing-name: a control with no accessible name. An identifier, a resource id, or a field value is not a name; a label, an Android content description, a placeholder, or a named child is.ambiguous-name: two or more evaluated controls of one role share one accessible name on the captured screen, for example three buttons named “Save”. Names that differ only by case or surrounding whitespace count as one name. Each affected control gets its own finding, and the detail gives the shared label and the count. Controls of different roles may share a name.covered-control: a control or row the snapshot already marks[covered]. Audit reports covered controls inside scroll containers, including those under sheets and dialogs. A control or row under a persistent bar (tab bar, toolbar, navigation bar, bottom navigation) is not reported when scrolling can reveal it: the snapshot marks the coverscrollCanReveal: trueincoveredBy, which means a scroll container of the node reports hidden content toward the bar and its frame reaches beyond the bar on the bar-free side. Controls and rows no scroll can reveal, such as a fixed control or a list already scrolled to its end, are still reported.
Controls are recognized by role (button, link, switch, checkbox, radio, slider, menu item, text and search fields). On Android, a node the capture reports as clickable or long-clickable with no control role — a custom touchable such as a React Native Pressable without an accessibilityRole — is evaluated as a control too. Such a node reports its findings under role clickable, a role the snapshot itself never shows, and it joins the shared-name check only when it has a name of its own. One named only by its descendants is excluded: TalkBack announces it by joining their text, so a shared first child does not mean a shared announced name. iOS visibility relies on the hittable fact. Size and name checks skip system bars, keyboard keys, and UIKit sheet grabbers. Direct items of recognized native iOS navigation bars, toolbars, and tab bars skip target-size checks and still receive missing-name checks. Custom bar children and items inside nested content containers remain subject to size checks. A system-generated accessible name, such as “add” or “remove” for an icon-only React Native Pressable on iOS 26, prevents a missing-name finding. The audit cannot determine whether the app supplied that name. When a control is the only child of a control with the same role, the child drops a finding only if the parent reports the same kind of finding. The same holds for a clickable Android container whose only actionable descendant is already a control: the pair reports once on the container, for each finding kind the container reports itself.
Like find, audit publishes only the refs it returns. The text prints each as @eN~s<refsGeneration>; press that pinned ref. A plain ref from before the audit stays refused after the frame expired, and an audit with no findings issues no refs. An audit with findings also ends the snapshot’s complete frame, so take a new snapshot before you use refs that the audit did not return. Each finding shows its role. Missing-name findings omit labels rejected by the name check and show the captured identifier when available. Other findings include the captured label when available. A control can get its name from a child or placeholder even when it has no label of its own, and the shared-name check reads that same resolved name. Guidance follows once per finding kind, with Apple HIG sizes on iOS and Material sizes on Android. --json returns findings (with label and identifier when available), guidance keyed by finding kind, checks, limitations, and refsGeneration (only with findings). checks.snapshot is unknown when the capture cannot report truncation, such as Appium page source.
Wait and alerts
Wait for a duration, text, selector, strict absence, or stable UI.
agent-device wait <ms>|text <text>|@ref|<selector>|absent <selector> [timeoutMs]|stable [quietMs] [timeoutMs]Also accepts: common options: --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Wait for text, selectors, and timeouts.
Exact behavior: agent-device help wait.
Inspect, accept, or dismiss a platform alert.
agent-device alert [get|accept|dismiss|wait] [timeout]Supported targets: Read, accept, and dismiss system alerts.
Exact behavior: agent-device help alert.
agent-device wait 1500agent-device wait text "Welcome back"agent-device wait @e12agent-device wait 'role="button" label="Continue"' 5000agent-device wait absent 'label="Loading..."' 5000agent-device alertagent-device alert getagent-device alert wait 3000agent-device alert acceptagent-device alert dismisswaitaccepts a millisecond duration,text <value>, a snapshot ref (@eN), a selector, or strictabsent <selector>. Every form except a plain duration takes an optional[timeoutMs]. Selector waits, including those insidereplay, poll snapshot captures with the same backend and recovery asis.waitresolves selectors the same way asclick,fill,get, andis.wait absent <selector>is strict absence, not a visibility check: it passes only when a complete, readable capture has zero matches, so hidden or off-screen matches keep it pending. It rejects--scopeand--depth. Sparse, truncated, incomplete, and Android unreadable-content captures never satisfy it.wait text <value>matches a node whose label, identifier, or value contains the text, ignoring case. An enabled editable field never matches by its current value, or by a label that only repeats that value. Its identifier, a label distinct from the value, or the placeholder an empty field shows still match. Sowait textafterfillwaits until the app shows that text elsewhere, for example after Save. To check the field itself, useis text <selector> <value>orget text.wait @refneeds a snapshot from a priorsnapshotcommand. It resolves the ref to its label or text, then waits for that text, so a duplicate label can match a different element than the original ref. It uses the same text rule, so for a filled field whose text is its typed value it waits for that text to appear elsewhere; to wait for the field itself, use a selector such aswait 'id="email"'.- Wait failures carry
error.details.reasonin--jsonoutput:wait_target_absent: a positive wait never found a match.wait_target_present: strictwait absentreached its deadline with valid captures that still contained matches.predicate_failedmeans strictwait absentcould not prove absence because no valid capture arrived, with the final observation/diagnostic preserved.wait_capture_stalled: no readable capture arrived. Retriable.wait_deadline_exceeded: a later capture used up the budget after an earlier readable capture.wait_readiness_exhausted: the deadline ended while the iOS runner was still starting (readinessPhase: runner-start) or the Simulator app was still being found (target-discovery). Retry with a timeout that covers that work. The runner start keeps going on its own budget (10 minutes by default when no startup timeout is set), so the retry joins it; a start that spends that budget fails withrunner_start_budget_exhausted, and the next command starts over.wait_runner_restart_exhausted: the deadline ended while the runner was being restarted to recover a lost response. Retriable.wait_landmark_identity_mismatch: a replay destination guard refused the match.wait_stable_timeout: the UI did not settle.
- Branch on
readableCaptures,waitedMs,matches, andfirstMatchinstead of parsing error text.firstMatchcarries identity and text only; absence failures make no visibility or rect claim. - Polling wait timeouts, and a replayed wait refused with
wait_landmark_identity_mismatch, also carrycaptures,readableCaptures, andpollsso you can see where the budget went. Each poll hasstartedMs,durationMs, and anoutcome:readable,unreadable,retriable,deadline,runner-restart, orreadiness. Long waits keep the first 5 and last 25 polls. A wait that never saw a readable capture reports the error its polls hit, with that error’s code and retry details, instead of a generic timeout;wait stableand a never-readable strict absence keep their own diagnostics.logPathlinks the full request log. alert(same asalert get) inspects or handles system alerts on iOS simulator, macOS desktop, and Android permission dialogs. On iOS it also covers app-owned modal popups with native blocking markers. On the Apple XCUITest runner it also covers Safari’s own page prompts, such as “Open this page in …?”. The[timeout]argument is the wait window ofalert waiton every backend: it polls its whole window, accepted up to 2147453647 ms (~24.8 days); a longer window is refused asINVALID_ARGSwithdetails.reason: alert-wait-window-too-longanddetails.maxWaitWindowMsbefore anything runs, never shortened. On the Apple XCUITest runner,alert get <ms>also takes it as the runner’s budget for the read, clamped to 1500–25000 ms and 10000 ms without an argument; the first XCTest read foralert waituses the requested window capped at 25 s, and later reads use the remaining window with the same cap. The 1500 ms floor does not apply toalert wait. Other backends’get, and every backend’sacceptanddismiss, run their own fixed budgets and ignore it. Foralert, the runner’s main-thread watchdog is that same budget. Analert getit cuts off reportsreason: runner_main_thread_timeoutwithdispatched: unknown: it does not mean there is no alert, which isalert-not-found. The nextalert getwaits out the runner’sRUNNER_BUSYrefusal while the abandoned work drains, then runs; the resends are bounded, so if the work has not drained by then it still returnsRUNNER_BUSY(dispatched: no) and you retry.- On the snapshot-derived Android backends
alert get --jsonanswers with a typedstatus:visible,none, orundecided(an alert-shaped capture that resolves to no single alert). Branch onstatus, not on the message. - On those backends,
alert acceptpresses the lasting grant when a permission sheet offers several: Android orders its grants by the platform’s own ids (full-access “Allow all”, then foreground-only, then always, then the picker-limited “Select photos and videos”, then one-time) whatever the button language — this is what makes the Android 14+ partial-media sheet answer “Allow all” — and elsewhere the English label table decides (“while using the app” over “only this time”). Android acts only on the grant ids it declares with a role and a rank; a sheet carrying an allow- or deny-shaped grant id it does not declare (a vendor fork’s own button, or a newer Android grant) is refused for bothacceptanddismiss—dismissanswers with the Back key, the cancel that grants nothing. A sheet whose choices no rank orders — or that names the same choice at two points — is refused withalert_button_undecidedanddispatched: no, never pressed by position; read the labels withalert getand press your choice by label/ref. - On those backends, when
alert accept/dismissfails before pressing anything,error.details.reasonnames why (a capture or transport failure that is not a driver refusal may instead surface as its own error without areason). A budget never cancels a running capture or press: it only ends the polling loop, so every check that started inside the budget finishes and counts. Before any press,dispatched: noand the reason isalert-not-found(the action budget ended with no alert on screen),alert_capture_undecided, oralert_button_undecided(the sheet is too ambiguous to act on). After a press,dispatchedis absent and the reason isalert-window-expired; “did not dismiss the visible alert” means the latest post-press capture that answered named the same dialog again, “could not be confirmed” means the press went out but the latest read was unresolvable or never answered, so the dialog may already be gone. If you cancel the request at any point from the press onward — the tap in flight, or the post-press checks — the cancellation reportsdispatched: unknown: the device may already have received the tap. The one exception is a cancel whose post-press check nevertheless finished and proved the alert gone; then the command reports the handled alert, because the outcome is known. Runalert getbefore acting again. - On those backends a slow capture is never lost to its budget: a check that straddles the deadline still answers, which is why a quiet
alert accept/dismissalways reportsalert-not-foundand never a timing-dependent failure (alert getanswersstatus: noneandalert waittimes out on a quiet screen withdetails.reason: "alert-wait-timeout"). The cost is a wait: the command stays open until the capture it started returns. On Android your cancellation stops the capture and the tap (the adb child is killed). Limrun iOS uses the Apple runner and its cancellation and deadline behavior. - Use
alert getfor a quick check, andalert wait <short-ms>only when a prompt may appear after async work. Don’t usesettings permissionto answer a dialog already on screen; it is for setup before a flow. acceptanddismissare sent once on every platform and never replayed, even if the response is lost. On iOS the runner activates the button once, then only observes until the alert disappears, changes, or the deadline expires. A changed alert does not prove a permission was granted; verify the app outcome.- The Apple XCUITest runner (iOS, tvOS, and visionOS simulators and devices) and Limrun iOS use the same English label preferences after finding an alert:
Allow While Using AppoutranksAllow Once, and equal-ranked choices refuse.Open,Done, andConfirm…accept;Keep Browsing,Deny, andSkipdismiss. On iOS simulators, including Limrun, the XCUITest runner also recognizes the wording of these labels in each of the device’s preferred languages, read from the OS’s own notification, privacy (including App Tracking Transparency), location, andOpen in …?launch-confirmation prompt strings, at the rank of the English label they translate. The translations apply to any alert whose labels match them, not only permission prompts; a translation both roles claim stays unknown. If a notification, privacy, or location table cannot be read, the runner drops the permission translations and keeps the English labels; theOpen in …?table is read apart, so its labels survive that, and the permission translations survive it being unreadable. Physical iOS devices, tvOS, and visionOS always use the English labels. On iOS simulators, including Limrun,alert getmarks theOpen in …?launch confirmation withlaunchConfirmationPrompt: true;openreads that mark to answer the prompt. Unknown labels refuse even for a lone button; readalert get, then choose explicitly withsnapshot -iandpress @ref. Ordinary Android dialogs also recognize these labels; Android permission-button ids keep priority. - On the Apple XCUITest runner,
dismissactivates only a button its decline list recognizes (Cancel,Don't Allow,Ask App Not to Track, and similar English labels), or the close button of a popover whose native marker reads “dismiss popup”. It never taps anything else: unknown, reworded, or localized decline copy outside the preferred languages’ prompt strings fails witherror.code: ALERT_BUTTON_NOT_FOUNDanddetails.dispatched: no, tapping nothing, rather than guessing at an affirmative (#3627). A button choice that finds no button to name answers with that code anddispatched: noforaccepttoo. To answer a prompt with unrecognized wording, read the labels withalert get, then press the button by label throughsnapshot+press @ref. The macOS helper’sdismisskeeps its own rules (the app’s cancel-button attribute, its label list, and a last-button fallback). - An unreadable or ambiguous capture after the action fails with
error.details.runnerErrorCode: ALERT_CONFIRMATION_UNAVAILABLE; an expired runner deadline during action or confirmation after the alert is resolved fails withALERT_DEADLINE_EXCEEDED. Neither proves the alert is gone or that nothing happened. Runalert getbefore acting again. - iOS runner refusals carry
error.details.reason:runner_busymeans the runner ran nothing (dispatched: no); a read-only command resends it until shortly before its own timeout, anddetails.attemptscounts the sends. A read inside an action, such as the viewport read before a swipe, sends it at most 8 times in total, asdetails.attemptsreports, because the action needs the rest of its timeout. When that window closes first, the command still fails withrunner_busy(dispatched: no), so retry the read;runner_main_thread_timeoutmeans the action may still land (dispatched: unknown);no_text_input_at_pointandtext_input_probe_unavailablemean afillrefused before dispatching anything (dispatched: no) — see Text entry below. A synthesized long press,scroll,swipe(sent as a planned flinggesture), or other plannedgesturethat the event synthesis refuses before its event record is handed to XCTest reportsCOMMAND_FAILEDwithsynthesized_gesture_not_dispatched(dispatched: no), and so does a plannedgesturerefused while its window or display is resolved (the window cannot be named, or the sole display cannot be measured); one that fails after the record was handed to XCTest (its events may or may not have run) reportssynthesized_gesture_outcome_unknown(dispatched: unknown) and is never repeated through an XCTest fallback, so check the screen withsnapshotbefore you retry. Any other refusal, such as a platform without touch input, keepsUNSUPPORTED_OPERATION. A long-press step in a press series reports the same reasons; once an earlier step has run, the series isdispatched: unknown.back_swipe_no_changemeans the iOSbackswipe was sent and the screen did not change, andback_swipe_unverifiedmeans it was sent but may or may not have navigated (bothdispatched: unknown);back_swipe_not_dispatchedmeans it was refused before any touch went down (dispatched: no). On the native iOS runner, a visible keyboard makeskeyboard dismissreturnkeyboard_dismiss_unavailablewithdispatched: no. An unreadable keyboard state returnsOBSERVATION_UNAVAILABLE. Ifkeyboard enterreturnskeyboard_return_unavailable, check the screen before retrying because Return may have reached the app. A press the runner answers that its target cannot perform — today the Action Button on an iPhone or iPad model that has none, since the simulator volume and non-tvOS remote cases are refused before the runner is reached — keepsUNSUPPORTED_OPERATIONand reportshardware_control_unavailable(dispatched: no, nothing was pressed). macOSbackfinding no in-app back control reportsin_app_back_control_unavailableunderCOMMAND_FAILED(dispatched: no). See Back above. - On the Apple XCUITest runner, an alert search that fails, runs out of time, or finds an app alert, Safari dialog, or dismiss-popup window with no actionable controls fails with
error.code: ALERT_UNRESOLVEDanddetails.dispatched: no.alert getreports it at once.accept,dismiss, andalert waitretry it within their windows, like absence, and report it, not a timeout, when the last check remained unresolved. Inspect the prompt withscreenshot, thensnapshot -i, andpress @refon the visible button. - On the Apple XCUITest runner,
alert getdescribes a readable alert even when all its buttons are disabled, and lists those disabled buttons.alert acceptandalert dismissfail withALERT_BUTTON_NOT_FOUND. - If a sheet or permission prompt is visible but
alertreports none,alertdid not recognize it. Runsnapshot -i -s "<visible label>", thenpress @refon the visible button. Android alert support is snapshot-derived, and not every iOS simulator permission surface is a native alert.
Interactions
Click or tap a UI target.
agent-device click <x y|@ref|@ref,...|selector>| Option | What it does |
|---|---|
--count <n> |
Repeat count for press, swipe and gesture tap series |
--interval-ms <ms> |
Delay between press iterations |
--hold-ms <ms> |
Press or gesture tap hold duration for each iteration; for gesture pan, the hold before the move |
--jitter-px <n> |
Deterministic per-axis coordinate jitter in pixels |
--double-tap |
Use double-tap gesture per press iteration |
--verify |
Capture cheap post-action evidence (AX digest, node counts, changedFromBefore) instead of a follow-up snapshot |
--button primary|secondary|middle |
Click: choose mouse button (middle reserved for future macOS support) |
Also accepts: common options: --settle, --settle-quiet <ms>, --timeout <ms>, --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Tap, press, and fill.
Exact behavior: agent-device help click.
Short-press a UI target.
agent-device press <x y|@ref|@ref,...|selector>Aliases: tap.
| Option | What it does |
|---|---|
--count <n> |
Repeat count for press, swipe and gesture tap series |
--interval-ms <ms> |
Delay between press iterations |
--hold-ms <ms> |
Press or gesture tap hold duration for each iteration; for gesture pan, the hold before the move |
--jitter-px <n> |
Deterministic per-axis coordinate jitter in pixels |
--double-tap |
Use double-tap gesture per press iteration |
--verify |
Capture cheap post-action evidence (AX digest, node counts, changedFromBefore) instead of a follow-up snapshot |
Also accepts: common options: --settle, --settle-quiet <ms>, --timeout <ms>, --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Tap, press, and fill.
Exact behavior: agent-device help press.
Focus input at screen coordinates.
agent-device focus <x> <y>Supported targets: Refs, selectors, element lookup, and attribute reads.
Exact behavior: agent-device help focus.
agent-device click @e1agent-device click @e1 --button secondary # macOS secondary click / context menuagent-device click @e13,@e14 # one plan, one admission passagent-device press @e13,@e14 # a two-key plan; up to 16 refsagent-device focus @e2agent-device fill @e2 "text" # Replace the field valueagent-device fill @e2 "search" --delay-ms 100printf %s "$PASSWORD" | agent-device fill @e2 --text-stdin # Text from stdin, kept out of argvagent-device type "text" # Type into focused field without clearingagent-device type "query" --delay-ms 100agent-device press 300 500agent-device press 300 500 --count 12 --interval-ms 45agent-device press 300 500 --count 6 --hold-ms 120 --interval-ms 30 --jitter-px 2agent-device swipe 540 1500 540 500agent-device swipe 540 1500 540 500 --count 8 --pause-ms 30 --pattern ping-pongagent-device gesture pan 200 420 0 -80 500agent-device gesture pan 200 420 80 -40 700 --pointer-count 2agent-device gesture fling right 200 420 180agent-device gesture drag 'id="drag-source"' 'id="drop-target"'agent-device gesture drag @e4~s12 'label="Archive"' 700 600 200agent-device longpress 300 500 800agent-device hover @e12 --settle # Web only: move the pointer without pressingagent-device scroll down 0.5agent-device scroll down --pixels 320agent-device scroll down --until 'label="Sign in"'agent-device scroll refresh # pull-to-refresh at the top of the listagent-device gesture pinch 2.0 # zoom in 2xagent-device gesture pinch 0.5 200 400 # zoom out at coordinatesagent-device gesture rotate 35 200 420 # rotate app contentagent-device gesture transform 200 420 80 -40 2 35 700 # combined pan, zoom, and rotateagent-device gesture tap 80 300 200 450 310 600 # three fingers at onceagent-device gesture tap 80 300 200 450 --count 20 --pause-ms 100 # repeated two-finger tapIf rotation stops repeated iOS presses, inspect the screen before continuing with the remaining presses.
A successful click or press means the action was sent to where the command found the target. It does not confirm that the element received it or that the screen changed. When the next step depends on it, add --verify (reports changedFromBefore), add --settle (returns the diff once the UI goes quiet), or follow with wait <selector>. Before retrying a failed interaction, see Retry after a failed command.
--settle compares trees in the view of the refs you last read. After a full snapshot, it reads the full tree and issues full-tree refs; after snapshot -i, it reads the interactive view. It also preserves -d, -s, --raw and --actions. This holds for press, click, fill, longpress, scroll and back, including ref, selector and coordinate targets.
Standalone --verify captures in the pre-action tree’s view, which can differ from the last ref frame when a selector resolves a fresh tree. With --settle --verify, verification reuses the settled capture and reports changedFromBefore only when the two views match or a known surface transition occurred. Without a populated baseline, post-action captures use the interactive view.
A click or press whose target the daemon resolves to a point (@ref or selector) re-checks that target’s position before dispatching when the session’s previous action animated the screen, and dispatches where it came to rest. When that check cannot confirm a stable position — the target was still moving, or a re-check could not measure it — the command refuses with target_still_moving and dispatched: no: nothing was dispatched, the point the command resolved is in error.details.rect, and where the target was last seen is in error.details.movedToRect when that last look measured one. Run wait <selector> on the target and retry the same command, or add --settle so the action waits for the UI to go quiet. A refused @ref press needs a fresh snapshot -i and a selector, because the wait retires the ref. Two dispatch paths hand off before the check: a press at raw coordinates has no resolved target to re-check, and a dispatch the backend performs on the element itself — click @ref on a backend with element dispatch, or a Maestro non-hittable coordinate fallback — goes to that backend rather than through a resolved point. On iOS, a runtime-resolved click or press whose target is a control nested inside a larger touch control — a swipe action beside its row — also asks the runner whether the platform reports that control as hittable. When it does not, the command refuses with target_not_hittable and dispatched: no, because a tap at the control’s centre would land on another element; error.details.rect is where the command resolved it. Maestro replay is the exception: a click that carries allowNonHittableCoordinateFallback skips this read, taps resolved bounds, and on the direct-iOS selector route sends the selector straight to the runner, which may use the non-hittable coordinate fallback. Reveal the control (for example swipe its row) and take a fresh snapshot -i. An answer the runner cannot tie to the target — no selector, an ambiguous match, another frame — lets the press proceed as before. Other presses pay no extra read. The re-check stops when the request is canceled or reaches its deadline, and nothing is dispatched (dispatched: no): a canceled request fails with details.reason: request_canceled, and a request out of time with details.reason: daemon_request_timeout.
A comma-separated ref plan — press @e13,@e14 or the same form on click — dispatches 2 to 16 snapshot refs as one command. The whole plan resolves and admits against the current ref frame before the first press (run snapshot -i first and copy the refs exactly); a repeated ref dispatches the same key twice. The first press expires the frame, and the later keys dispatch at the points the snapshot admitted — no member re-resolves. A refusal before the first press leaves the frame active with dispatched: no; a refusal after the first press reports details.dispatchedSteps (keys already dispatched), details.refPlanKey (the refused key), and details.refPlanPending (the keys that did not run) — replan from a fresh snapshot -i, because the frame stays expired; a failed plan returns those error details, not sequence.points. On a successful response, ref stays the first key and sequence.points holds every dispatched point. While script recording is armed, the plan refuses unless the step passes --no-record, because the recorder binds one target per step: record one press per key. This is ADR 0014’s multi-ref logical command; see ADR 0014.
Text entry
Replace text in a UI input.
agent-device fill <x> <y> <text> | fill <@ref|selector> <text> | fill <x y|@ref|selector> --text-stdin| Option | What it does |
|---|---|
--delay-ms <ms> |
Delay between typed characters |
--record-as <VAR> |
Fill: send the live text but publish ${VAR} in an armed .ad recording |
--text-stdin |
Fill: read the text from stdin (max 64 KiB, one trailing newline removed) instead of argv |
--verify |
Capture cheap post-action evidence (AX digest, node counts, changedFromBefore) instead of a follow-up snapshot |
Also accepts: common options: --settle, --settle-quiet <ms>, --timeout <ms>, --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Tap, press, and fill.
Exact behavior: agent-device help fill.
Append text to the focused input.
agent-device type <text> [--delay-ms <ms>]| Option | What it does |
|---|---|
--delay-ms <ms> |
Delay between typed characters |
Supported targets: Type into the focused field.
Exact behavior: agent-device help type.
fillreplaces the field value.typeappends to the focused field and accepts text only: usefill @ref "text"to target a field, orpress @refthentype "text".- iOS, including Limrun,
fillavoids another focus tap when the current command identifies the target input, reads its keyboard focus, and finds no other input under its point. For readable focused inputs, clearing tries select-all/delete and reads the result before moving the caret for delete-burst fallback. Newly focused inputs retain caret preparation. A masked input, such as a secure field, is not cleared when it shows nothing or a placeholder that is not a mask. Otherwise it gets deletes with read-back first, and the caret tap at the field’s right edge, where a show/hide control often sits, runs only when the read-back shows neither an empty value nor a masked placeholder. If the deletes can’t reach the text, for example after the caret was moved off the end, and that text shows as many bullets as the placeholder, the read-back can’t tell it from empty, so the new text is typed at the caret, next to the old text. - Use plain
fillortypefirst. Add--delay-msonly when a debounced or search-as-you-type field misses characters, or the app must receive each incremental update; delayed typing enters characters one at a time instead of using a clipboard-style fallback. fill --text-stdinreads the text from stdin so a secret never appears in process arguments. Pipe it withprintf %s. It reads at most 64 KiB, removes one trailing newline, and refuses a terminal, empty input, invalid UTF-8, or an extra text argument. Output shows the value as${VAR}with--record-as <VAR>and as[REDACTED]otherwise, including in error messages and details, and in therequested,before, andafterread-back of an unconfirmed fill, which can hold a reformatted form of the value. With--settle, the diff line text and tail labels are replaced whole, so text around the value in the field is not shown either; refs and counts stay. While script recording is armed, pass--record-as <VAR>or--no-record; passing neither is an error. Batch steps don’t accept it.- The privacy controls for typed input (
--text-stdinand--record-as) keep the literal out of agent-device’s own responses, diagnostics, and recorded scripts. They do not rewrite what the platform records: on iOS, XCTest writes its own diagnostic logs and its.xcresultbundle, and typed text can appear in both, on a simulator or a physical device. Treat those as sensitive, and use test-only credentials when they may be kept or shared. See Security and trust. - Android text entry is owned by
agent-device. Don’t fall back to rawadb, clipboard, or paste; if non-ASCII is unsupported on the current backend, report the gap. Androidfillverifies the text and fails instead of retrying when the IME captures input.
Text-entry errors and what to do:
TEXT_INPUT_NOT_FOCUSED(type, iOSfill): focus a visible text input and retry. If accessibility does not expose the input, focus it by coordinates. An iOSfillwhose point lies on more than one input, as on a sheet or popover over a form, taps that point and waits for keyboard focus. It clears and types only into the input there that took keyboard focus from that tap. When none took it, an input there that already had focus is used only if it still has focus and is the only uncovered input there; otherwise the fill returns this code and types nothing. If the input you want already has focus, end editing using a visible control, then retry.NO_TEXT_INPUT_AT_POINT(iOSfillunder a degraded XCTest channel — coordinate, ref, selector, and replay fills all aim at a point): the runner identified no text input under that point and refused before dispatching anything (error.details.reasonisno_text_input_at_point,dispatched: no), so no field changed. A ref or selector fill aims at the centre of the rect it resolved to, so an outer container or a non-input node can land outside the real field: runsnapshot -i, pick the input node itself, and aim inside its rect.TEXT_INPUT_PROBE_UNAVAILABLE(iOSfillunder a degraded XCTest channel — coordinate, ref, selector, and replay fills all aim at a point): the runner’s input lookup could not answer, so it refused before dispatching anything (error.details.reasonistext_input_probe_unavailable,dispatched: no). This does not mean the point has no input. Retry the fill, or runsnapshot -ionce its capture reads back. A ref or selector fill aims at the centre of its resolved rect.TEXT_INPUT_SYNTHESIS_UNAVAILABLE(iOStype "\n"with the software keyboard hidden): show the software keyboard, then retry.TEXT_INPUT_COMMIT_NOT_OBSERVED(iOSfill): the runner could not confirm the text landed before its deadline, or the text equals the field’s placeholder. The field may hold none, part, or all of it. Runsnapshot -i; if it doesn’t match, retryfillwith the full text quoted and--delay-msset to the value in the error hint.TEXT_INPUT_CLEAR_NOT_OBSERVED(iOSfill): the old text was not seen cleared, so nothing was typed. Inspect withsnapshot -i, then retryfill.TEXT_INPUT_SYNTHESIS_BUDGET_EXCEEDED(iOSfill): the text is too long to type in one runner command, and nothing was typed. Fill up to the character limit the hint names for your--delay-ms, then append the rest withtype.--delay-mslowers the limit; a longer timeout does not help.TEXT_ENTRY_MISMATCH(iOSfill): the settled value contains only characters, in order, from the field’s value after clearing plus your text. That covers dropped characters and an unchanged value. This can also reject legitimate filtering, trimming, or masks (5into$0.00may show$0.05). Inspect the field and retryfillonly if it needs correction, using the--delay-msvalue from the error hint.
Except for TEXT_INPUT_SYNTHESIS_BUDGET_EXCEEDED, where you append the rest with type after the shorter fill, recover from these with fill, never type, which appends to whatever the field already holds. iOS fill types the replacement once and does not clear and retype a mismatch on its own. On the iOS accessibility route, nonempty fills wait until the confirmation deadline before reporting TEXT_ENTRY_MISMATCH.
On iOS, a single-line fill ending in a submit key, or a field that became unreadable or disappeared after typing, succeeds without verification; assert the resulting screen.
fill returns verification: "unconfirmed" when the field’s settled value differs from the request but no failure is proven, such as app formatting (00 062 91 77 for 000629177, $10.00 for 1000) or an OTP field announcing 6 of 6 digits. Missing, reordered, duplicated, or stale text can also produce it. Inspect requested, before, and after, then assert the value or the resulting screen:
agent-device wait 'id="field-phone" value="00 062 91 77"'Pointer and gestures
Hold a UI target to open a context menu.
agent-device longpress <x y|@ref|selector> [durationMs]Aliases: long-press.
Also accepts: common options: --settle, --settle-quiet <ms>, --timeout <ms>, --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Long press.
Exact behavior: agent-device help longpress.
Hover the pointer over a UI target (web only).
agent-device hover <x y|@ref|selector>Also accepts: common options: --settle, --settle-quiet <ms>, --timeout <ms>, --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Hover and viewport size.
Exact behavior: agent-device help hover.
Fling between coordinates.
agent-device swipe <x1> <y1> <x2> <y2> [--count <n>] [--pause-ms <ms>] [--pattern one-way|ping-pong]| Option | What it does |
|---|---|
--count <n> |
Repeat count for press, swipe and gesture tap series |
--no-post-gesture-stabilization |
Scroll, swipe, gesture swipe, open: skip the movement check and the stabilization wait that follow a gesture, and on a local iOS simulator the first-screen wait after an app launch; use it only when your own polling verifies the screen |
--pause-ms <ms> |
Delay between swipe or gesture tap iterations |
--pattern one-way|ping-pong |
Swipe repeat pattern |
Supported targets: Gesture plans and swipes.
Exact behavior: agent-device help swipe.
Run pan, fling, swipe, pinch, rotate, transform, tap, or drag gestures.
agent-device gesture <pan|fling|swipe|pinch|rotate|transform|tap|drag> ...gesture pan
| Option | What it does |
|---|---|
--pointer-count <1|2> |
Gesture pan: number of touch pointers (default 1) |
--hold-ms <ms> |
Press or gesture tap hold duration for each iteration; for gesture pan, the hold before the move |
gesture tap
| Option | What it does |
|---|---|
--count <n> |
Repeat count for press, swipe and gesture tap series |
--hold-ms <ms> |
Press or gesture tap hold duration for each iteration; for gesture pan, the hold before the move |
--pause-ms <ms> |
Delay between swipe or gesture tap iterations |
gesture fling
Reads no options.
gesture swipe
| Option | What it does |
|---|---|
--no-post-gesture-stabilization |
Scroll, swipe, gesture swipe, open: skip the movement check and the stabilization wait that follow a gesture, and on a local iOS simulator the first-screen wait after an app launch; use it only when your own polling verifies the screen |
gesture pinch
Reads no options.
gesture rotate
Reads no options.
gesture transform
Reads no options.
gesture drag
Reads no options.
Supported targets: Gesture plans and swipes.
Exact behavior: agent-device help gesture.
click --button secondaryopens a macOS context menu;--button middleis unsupported on macOS.longpressis supported on iOS and Android.hoveris web only: it moves the pointer over a target without pressing so hover-gated UI appears, and--settlereturns what it revealed. Touch platforms reject it; uselongpressfor the hold gesture.swipeis a quick, fixed-duration throw.gesture pan x y dx dy [durationMs]is a deliberate timed drag with one pointer, or two with--pointer-count 2. Repeated swipes allow at most 200 repetitions, 10000ms pauses, and 60000ms in total.gesture pan ... --hold-ms <ms>holds the contact at the start point for<ms>before moving, for hold-activated drag handles (reorder grips, long-press drags) that expose no accessibility element and so no @ref. Single-pointer only; hold plus duration is capped at 10000ms. Likegesture drag, it works on Android touch devices and iOS/iPadOS; other backends refuse it withUNSUPPORTED_OPERATIONbefore touching the screen.gesture fling up|down|left|right x y [distance]is a fast directional throw. Neitherswipenorgesture flingtakes a duration, andgesture rotatetakes no velocity; see Rewrite old gesture commands to update old scripts.gesture drag source destination [sourceHoldMs] [moveMs] [destinationHoldMs]holds one pointer down from source to destination. Endpoints are selectors or refs, resolved before dispatch and recorded as selectors, the same way as other recorded steps. Defaults are 800, 500, and 0ms, capped at 10000ms in total. It works on Android touch devices and iOS/iPadOS; other backends refuse it before touching the screen.gesture pinch <scale> [x] [y],gesture rotate <degrees> [x] [y](the sign sets direction),gesture transform x y dx dy scale degrees [durationMs], and two-fingergesture panwork in Android, iOS, and iPadOS app sessions, on simulators and physical devices. On Apple they use the XCTest runner, so iOS sessions reached through a WebDriver provider refuse them. One-fingergesture panworks wherever coordinate drags do. A path that does not fit the viewport fails before injection instead of being clamped. Useorientationto rotate the device.gesture tap x1 y1 x2 y2 [... x5 y5]touches 2 to 5 distinct points and holds them for--hold-ms(default 50ms, at least 16ms) before lifting.--countrepeats the same contacts up to 200 times with--pause-msbetween repetitions; the series must fit in 60000ms, counting about 500ms of overhead per repetition. It works in Android and iOS/iPadOS app sessions; WebDriver providers refuse it unless they declaretapGesturesupport. On iOS the contacts touch down and lift together; on Android they touch down up to 8ms apart and lift 8ms apart in reverse order. Three or more fingers can trigger iOS system gestures such as undo, so verify app state afterwards. Usepressfor one finger.- Cancelled
gestureandswiperequests returnCOMMAND_FAILEDwithdetails.reason=request_canceledand record no action. Repetition pauses are interruptible. - On the native iOS runner, one-finger
gesture pancan cross into the area covered by the keyboard. Use it for an intentional drag where the app supports interactive keyboard dismissal. - App recognizers may not report exactly the requested pan, scale, and rotation. Verify app-level state such as
pan changed yes, and prefer separategesture pan,gesture pinch, orgesture rotatecommands when exact values matter. Seeagent-device help gestures.
Scroll
Scroll in a direction or to an edge.
agent-device scroll <direction|top|bottom|refresh> [amount] [--until <selector>] [--max-passes <n>] [--pixels <n>] [--duration-ms <ms>] [--settle]| Option | What it does |
|---|---|
--duration-ms <ms> |
Scroll: pace the gesture over this duration when supported |
--pixels <n> |
Scroll: explicit gesture distance in pixels |
--until <selector> |
Scroll: repeat passes until the selector is visible on screen |
--max-passes <n> |
Scroll –until: maximum gestures |
--no-post-gesture-stabilization |
Scroll, swipe, gesture swipe, open: skip the movement check and the stabilization wait that follow a gesture, and on a local iOS simulator the first-screen wait after an app launch; use it only when your own polling verifies the screen |
Also accepts: common options: --settle, --settle-quiet <ms>, --timeout <ms>.
Supported targets: Scroll.
Exact behavior: agent-device help scroll.
Things to know:
- A scroll does not land on an exact position. The amount is a fraction of the viewport (
0.5is half), and the app’s scroll physics decide the final offset. - To reach an off-screen element, use
scroll down --until <selector>. It also works in.adscripts on any screen size; see Replay and E2E testing. It stops after 12 gestures by default. For a long list, raise--max-passes(1–200 gestures). If the 90-second request timeout ends the search, inspect the screen and continue with another search. --settlereturns the settled diff with fresh refs for the changed screen, so you do not need anothersnapshot -ibefore the next action.- Read
movementin the result:moved,at-edge,unchanged, orunobserved. Afterscroll refresh,unchangedmeans that nothing changed on screen. It does not mean that a refresh ran and found nothing new, so check the app’s refresh indicator or content. scroll refreshis one slow pull down (scroll up 0.4 --duration-ms 1200by default; an amount,--pixels, or--duration-msoverrides it). On iOS, the pull runs down the middle of the screen. A list that sits only in the top or bottom part of the screen is not pulled.- With a keyboard up, the scroll stays above the keyboard and leaves it open. The result reports this as
keyboardAvoidedandkeyboardMinY. If too little room is left, end editing first. On Android, usekeyboard dismiss. On iOS, use a visible dismissal control. - A refused scroll names its cause in
details.reason, and the hint gives the next step. The reasons arescroll_refresh_not_at_top(runscroll topfirst),scroll_keyboard_occludes_surface, andscroll_no_progress. With--until, they arescroll_until_pass_limit,scroll_until_edge_reached,scroll_until_no_progress, andscroll_until_capture_unreadable. Forscroll topandscroll bottom, they arescroll_edge_pass_limit,scroll_edge_no_progress, andscroll_edge_capture_unreadable.--max-passeswithout--untilfails withINVALID_ARGSandscroll_max_passes_requires_until. The CLI and MCP check the range first: they reject an out-of-range value withINVALID_ARGSand no reason before the command runs, with or without--until. The Node client sends the value to the daemon. There, an out-of-rangemaxPasseswithuntilfails withINVALID_ARGSandscroll_max_passes_invalid, and one withoutuntilfails withscroll_max_passes_requires_until. --no-post-gesture-stabilizationis for a caller that verifies the screen by polling it, such as a test runner. Without your own polling, the next read can return a tree that the gesture is still moving. In the Node client or a batch step, passpostGestureStabilization: false. To apply it to every command, setpostGestureStabilizationtofalsein your user config, or setAGENT_DEVICE_POST_GESTURE_STABILIZATION=0../agent-device.jsonrejects the key, a recorded.adscript does not carry it, and MCP and AI SDK tools do not offer it.
Retry after a failed command
If an Apple runner returns COMMAND_ALREADY_FINISHED, it has already finished that command ID and cannot replay its outcome. Run snapshot -i to inspect the result before deciding whether to send another interaction.
When a command fails, read error.details.dispatched before you retry:
no: the action never reached the device. Checkdetails.reasonbefore retrying; a bounded resource refusal must run as a separate command.unknown: the action may have landed. Take a snapshot before you retry; a blind retry can tap, type, or navigate twice.- Missing: no guarantee. Treat it as
unknown.
For a failed batch or replay, inspect completed steps and details.dispatchedSteps first. A
resource step refused with details.reason: bounded_composite_resource_unsupported has
details.dispatched: no for that step. details.standaloneCommandName names a known public
command; it is not a complete command. Run the original step separately with its original
arguments and options, the same --session value, and the same private CLI context. Earlier
steps may still have run.
Read-only commands such as get, snapshot, and wait report no, and so do record, trace,
and perf, whose controls the device refuses to repeat. On Android, dismissing a blocking system
dialog or ANR prompt first does not count as a dispatched step. For other failures, once any step
of a request reached the device, the failure is unknown and error.details.dispatchedSteps
counts those steps. A bounded resource refusal reports no for its refused step even when earlier
batch or replay steps changed the app; check dispatchedSteps before retrying.
These refusals carry dispatched: no and a typed error.details.reason, so branch on the reason, not the message:
session_or_device_selector_required: the request had neither an active session nor a device selector. Open a session or pass--platform. Commands that require a session or a device selector before they read the request’s target (boot,clipboard,push,apps, and siblings) answer this even when the request named a session the daemon does not hold.named_session_not_found: the request named a session this daemon does not hold, with no device selector to fall back on (or no selector it can answer without the session —appstateon an Apple target refuses this even with an explicit device). The daemon lost its sessions (replaced or restarted), or the name is wrong;agent-device session listshows what it holds. Commands that require a session before they read anything else (interactions,findclicks, RN tooling,screenshot-style generic commands) answer the same missing-session cause as a message-levelSESSION_NOT_FOUNDcarrying nodetails.reason— some carry adispatchedstamp from the disclosure layer, some carry nodetailsat all; read the cause from the message, and read a presentdispatchedwith its usual meaning.session_app_required: a per-app setting was requested but the session binds no app and none was named. Runopen <app>, or name the app on the request for a setting that takes one (settings clear-app-state com.example.app).app_not_installed: the named app resolves to no installed app on the target. Runapps --allfor the exact bundle id or package, or install the app, then retry.malformed_request: the local socket transport refused the request envelope before any handler read it, for example a positional that is not a string. Fix the client that built the request; resending it unchanged fails the same way.remote_daemon_unavailable: the client’sGET /healthprobe of the remote daemon answered nothing usable, so the command did not run, anddetails.daemonBaseUrlnames the daemon that failed the probe. When the probe before the first send gets a server error or no answer in time, it waits a second and probes again, for up to the command’s own timeout, then refuses. A probe that gets no answer takes up to 3 seconds before that wait. A command that gets through then runs with its full timeout, so the whole request can take up to about twice that timeout. A connection that is refused outright fails at once.details.attemptscounts the probes, anddetails.healthRecoveryBudgetMsis set to the timeout when the probes used all of it. The probe a restart retry runs after the daemon instance changed refuses it too — there the first request reached the daemon but was refused before execution, so nothing ran either way. Make that daemon reachable, or clear or override--daemon-base-urlorAGENT_DEVICE_DAEMON_BASE_URL; for a savedconnectconnection, rundisconnectto return to the local daemon, then resend the same command.webdriver_route_unsupported: on a WebDriver-backed device cloud, the driver does not implement the route; the limit is the cloud’s driver, not the device. A command with a second route (orientationhas two) tries it before failing. After an ambiguous failure on that transport, only read-only requests are resent.
Find (semantic)
Find an element and act.
agent-device find <locator|text> [action] [value] [--first|--last]| Option | What it does |
|---|---|
--record |
Force-record this action into a repair-armed heal; per-invocation only, the retired config key “record” no longer opts in (mutually exclusive with –no-record) |
--first |
Find: pick the first match when ambiguous |
--last |
Find: pick the last match when ambiguous |
Also accepts: common options: --depth, -d <depth>, --raw.
Supported targets: Refs, selectors, element lookup, and attribute reads.
Exact behavior: agent-device help find.
agent-device find "Sign In" clickagent-device find label "Email" fill "user@example.com"agent-device find role button clickagent-device find "Follow" listfind locates an element by text, label, or role and runs an action on it (click by default). See Selectors for the action list, ambiguous matches, and --first/--last.
Assertions
Check a UI predicate on a selector.
agent-device is <predicate> <selector> [value] [--depth, -d <depth>] [--scope, -s <scope>] [--raw]| Option | What it does |
|---|---|
--record |
Force-record this action into a repair-armed heal; per-invocation only, the retired config key “record” no longer opts in (mutually exclusive with –no-record) |
Also accepts: common options: --depth, -d <depth>, --scope, -s <scope>, --raw.
Supported targets: Refs, selectors, element lookup, and attribute reads.
Exact behavior: agent-device help is.
agent-device is visible 'role="button" label="Continue"'agent-device is exists 'id="primary-cta"'agent-device is absent 'label="Loading..."'agent-device is hidden 'text="Loading..."'agent-device is editable 'id="email"'agent-device is selected 'label="Wi-Fi"'agent-device is checked 'role=switch label="Wi-Fi"'agent-device is text 'id="greeting"' "Welcome back"isevaluates UI predicates against a selector expression and exits non-zero on failure. It takes selectors, not refs like@e3, and the same snapshot flags asclick,fill,get, andwait.- Supported predicates are
visible,hidden,exists,absent,editable,selected,checked,focused, andtext. is checkedpasses only on a checkable control (switch, checkbox, radio) whose snapshot state is explicitly checked; an iOSmixedstate or a control with no checked state fails it.is visiblepasses when the element is in the visible viewport, or has no rect of its own but sits inside a visible ancestor.is existsonly checks that the selector matches.is text <selector> <value>compares the element’s text with the value.wait textchecks that text is present, not that it can be tapped.is absentpasses only when the selector has zero matches in one readable, complete, settled, unscoped, full-depth capture. It does not mean hidden:--scopeand--depthare rejected, and sparse, unreadable, truncated, unsettled, or loading captures fail.- Predicates that name one element (all except
existsandabsent) andget attrsfail withAMBIGUOUS_MATCHwhen the selector matches more than one node; that is not a missing element.error.details.matcheshas the count, and up to five candidate@refs are listed, pinned toerror.details.refsGeneration, so you can act on one directly. Without a stored tree (a sparse capture), only the count is reported. See Selectors. - On iOS, React Native text appears as two nodes with the same label. Selectors that must resolve one element (
is,get attrs,screenshot --crop-on, replay) treat the pair as one;find ... listandsnapshot --jsonshow both. - On the web, on-screen text the browser cannot hand an action to (static text, a
statusannouncement) is in the tree and readable bywait text,find text,get text, andtext=, but carries no@refand has no rect:find ... listprints it as(no ref), and it is never a tap target. Such text is published onvalue, sovalue="X"can match page text as well as a field holding that text, and a predicate that needs one element then reportsAMBIGUOUS_MATCH; usetext=for page text, or addeditable=trueto name the field. - The first read after
scroll,swipe, orgesture swipewaits for two captures to agree. When that proves something about the gesture,is,get,find,wait, interactions that captured it, andsnapshotadd a warning, and all butsnapshotreportpostGestureOutcome({ "kind", "gesture": { "action", "positionals" } }) indataorerror.details:kind: "unsettled": the screen was still changing (after a gesture, or a first screen afteropenthat never quieted). A miss is not proof of absence; read again.is absentrefuses withobservation: "unsettled", andwait absentkeeps polling.kind: "loading": the app thatopenlaunched still showed no first screen when the wait ran out. A miss is not proof of absence.is absentrefuses withobservation: "loading", andwait absentkeeps polling.kind: "no-effect": nothing changed. The list may be at its edge or ignore synthesized scrolls; a rawswipe x1 y1 x2 y2inside it moves such lists. The soft keyboard appearing or going away counts as a change only when the pre-gesture baseline and a later quiet capture both read the keyboard from their own tree and disagree: the iOS XCTest runner and the iOS Simulator AX bridge (the default Simulator route) do, a WebDriver (Appium) visibility probe does not. The AX bridge reads the keyboard as gone only from a complete tree that holds no keyboard window. Otherwise only the content is compared.
- A caller that verifies the screen by polling it can skip that wait, and with it these outcomes, using
--no-post-gesture-stabilization(see Scroll).
Replay
Replay a recorded session or Maestro flow.
agent-device replay <path> | replay export <file.ad> [--out <path>]| Option | What it does |
|---|---|
--force, --overwrite |
Force replacement of existing state (connect: replace an active connection; –save-script: overwrite an existing target instead of refusing) |
--metro-host <host> |
Session-scoped Metro/debug host hint |
--metro-port <port> |
Session-scoped Metro/debug port hint; on an emulator/simulator the host defaults to the loopback alias, physical devices still need –metro-host |
--bundle-url <url> |
Session-scoped bundle URL hint |
--test-ime |
open/test/replay: activate the headless Android test IME for deterministic Unicode text entry (default on for emulators; opt-in on real devices; on test/replay it applies to the sessions the flow opens) |
--no-test-ime |
open/test/replay: keep the real Android keyboard even on emulators (opt out of the headless test IME; on test/replay it applies to the sessions the flow opens) |
--save-script [path] |
Arm a repair transaction from this replay (ADR 0012): recording starts at step 1, and the healed script commits when the repair-armed session tears down (close, close –save-script, or idle-reap). Independent of the open/close authoring arm-on-open. Optional custom output path. |
--update, -u |
Replay: retired as a rewrite (ADR 0012) — never edits the .ad file; every divergence already carries ranked selector suggestions, –update or not |
--from <n> |
Replay: resume at 1-based plan step n, skipping 1..n-1 without executing them (requires –plan-digest; see a divergence report’s resume field). replay only, not test |
--plan-digest <sha256> |
Replay: the plan digest a –from resume must match (from a prior divergence report); mismatch, edits, or include/platform-expansion changes fail INVALID_ARGS before any action |
--keep-session |
Replay: leave the session active by suppressing exactly an authored terminal close in a native .ad script; replay only, not test or Maestro YAML |
--maestro |
Replay: treat input as a supported Maestro YAML subset; unsupported syntax fails loudly. See agent-device help maestro for commands and boundaries |
-e KEY=VALUE, --env KEY=VALUE |
Replay/Test: inject or override a ${KEY} variable for the script (repeatable) |
Also accepts: common options: --timeout <ms>, --out <path>.
Exact behavior: agent-device help replay.
Run replay test suites.
agent-device test <path-or-glob>...| Option | What it does |
|---|---|
--metro-host <host> |
Session-scoped Metro/debug host hint |
--metro-port <port> |
Session-scoped Metro/debug port hint; on an emulator/simulator the host defaults to the loopback alias, physical devices still need –metro-host |
--bundle-url <url> |
Session-scoped bundle URL hint |
--test-ime |
open/test/replay: activate the headless Android test IME for deterministic Unicode text entry (default on for emulators; opt-in on real devices; on test/replay it applies to the sessions the flow opens) |
--no-test-ime |
open/test/replay: keep the real Android keyboard even on emulators (opt out of the headless test IME; on test/replay it applies to the sessions the flow opens) |
--update, -u |
Replay: retired as a rewrite (ADR 0012) — never edits the .ad file; every divergence already carries ranked selector suggestions, –update or not |
--maestro |
Replay: treat input as a supported Maestro YAML subset; unsupported syntax fails loudly. See agent-device help maestro for commands and boundaries |
-e KEY=VALUE, --env KEY=VALUE |
Replay/Test: inject or override a ${KEY} variable for the script (repeatable) |
--fail-fast |
Test: stop the suite after the first failing script; with sharding, each shard stops independently |
--retries <n> |
Test: retry each failed script up to n additional times |
--record-video |
Test: record each replay attempt to recording.mp4 in its attempt artifacts |
--artifacts-dir <path> |
Test: root directory for suite artifacts |
--reporter <name-or-path> |
Test: add a replay suite reporter; use default, junit:<path>, or a custom reporter path (repeatable) |
--report-junit <path> |
Test: compatibility alias for –reporter junit:<path> |
--shard-all <n> |
Test: run the full suite on each of n devices; combine with –device id1,id2 for explicit connected devices; AD_SHARD_INDEX is zero-based |
--shard-split <n> |
Test: split runnable suite entries across n devices; AD_SHARD_INDEX is zero-based |
Also accepts: common options: --timeout <ms>.
Exact behavior: agent-device help test.
agent-device open Settings --platform ios --session e2e --save-script [path]agent-device replay ./session.ad # Run deterministic replay from .ad scriptagent-device test ./suite # Run every .ad file in a folder or glob seriallyagent-device test ./suite --timeout 60000 --retries 1agent-device replay ./session.ad --from 4 --plan-digest <sha256> # Execute step 4; if already completed, use the next safe index with this digestagent-device replay ./session.ad --keep-session # Suppress its terminal close and continue interactively--save-script [path]onopenrecords a replay script when the session closes.replayruns deterministic.adscripts. Script paths are read on the calling machine, so the same command works with a local or remote daemon.--keep-sessionskips only an authored finalclose.testruns.adfiles, directories, or globs as a serial suite and streamspass/fail/skipon stderr (--verboseprints every result).--platformfilters by each script’scontext platform=...header,--timeoutand--retries(max3) apply per attempt, and--artifacts-diroverrides.agent-device/test-artifacts.- A failing step returns a
REPLAY_DIVERGENCEreport;replay --from <n> --plan-digest <sha256>resumes at plan stepn(testrejects--from). See Resume a failed replay. replay -u/--updateis accepted and does nothing; it does not rewrite the script.
See Replay and E2E testing for recording and CI workflow details, and Run Maestro flows for Maestro YAML.
Batch
Run multiple commands.
agent-device batch [--steps <json> | --steps-file <path>]| Option | What it does |
|---|---|
--steps <json> |
Batch: JSON array of {“command”,“input”} steps |
--steps-file <path> |
Batch: read steps JSON from file |
--on-error stop |
Batch: stop when a step fails |
--max-steps <n> |
Batch: maximum number of allowed steps |
Also accepts: common options: --out <path>.
Exact behavior: agent-device help batch.
agent-device batch --steps-file /tmp/batch-steps.json --jsonagent-device batch --steps '[{"command":"open","input":{"app":"settings"}}]'batchruns a JSON array of{ command, input, runtime? }steps in a single daemon request and stops at the first failing step.- In non-JSON mode, successful batches print a short per-step summary.
See Batching for payload format, response shape, and usage guidelines.
App install (in-place)
Install an app binary from a path.
agent-device install <path> | install <app> <path> [--os <version|range>] [--image-tag <tag>] [--device-mode <slim|full>] [--device-baseline <name>] [--physical]| Option | What it does |
|---|---|
--os <version|range> |
Proxy lease: OS version or range the backend picks the device by (Android: API level); refused without such a backend |
--image-tag <tag> |
Proxy lease: Android system image tag the backend picks the device by; refused without such a backend |
--device-mode <slim|full> |
Proxy lease: iOS simulator mode (slim or full) the backend leases; refused without such a backend |
--device-baseline <name> |
Proxy lease: saved device state (baseline) the backend restores on the leased device; refused without such a backend |
--physical |
Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend |
Supported targets: Install and reinstall an app.
Exact behavior: agent-device help install.
agent-device install com.example.app ./build/app.apk --platform androidagent-device install com.example.app ./build/MyApp.app --platform iosagent-device install ./build/entry-default-signed.hap --platform harmonyosinstall <app> <path>installs from a binary path without uninstalling first, keeping existing app data where the platform allows. Use it for upgrade flows.- Supports Android devices/emulators, iOS simulators, CoreDevice-backed iOS physical devices, and HarmonyOS devices. On xctrace-only devices, install the app with Xcode before opening it by bundle ID.
- Formats: Android
.apk/.aab, iOS.app/.ipa, HarmonyOS.hap. For an.ipawith several app bundles,<app>picks one by bundle id or name. A.hapinstalls from its path alone;agent-devicereads the bundle name from the archive, and<app>is a fallback hint. - On local Android and iOS targets, each install step times out after 120 seconds.
install,reinstall, anduninstallallow 480 seconds overall, including device startup. For.aab, building and installing the APK set each have a 120-second limit. .aabrequiresbundletoolinPATH, orAGENT_DEVICE_BUNDLETOOL_JAR=<absolute-path-to-bundletool-all.jar>withjavainPATH; it installs a universal APK.- Remote daemons upload local app files automatically; prefix the path with
remote:to use a path on the daemon host as is. A daemon that serves the public remote surface (proxy marker or auth hook) refuses daemon host paths with reasonREMOTE_HOST_INPUT_DENIED.
App reinstall (fresh state)
Replace an installed app with a new build.
agent-device reinstall <app> <path> [--os <version|range>] [--image-tag <tag>] [--device-mode <slim|full>] [--device-baseline <name>] [--physical]| Option | What it does |
|---|---|
--os <version|range> |
Proxy lease: OS version or range the backend picks the device by (Android: API level); refused without such a backend |
--image-tag <tag> |
Proxy lease: Android system image tag the backend picks the device by; refused without such a backend |
--device-mode <slim|full> |
Proxy lease: iOS simulator mode (slim or full) the backend leases; refused without such a backend |
--device-baseline <name> |
Proxy lease: saved device state (baseline) the backend restores on the leased device; refused without such a backend |
--physical |
Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend |
Supported targets: Install and reinstall an app.
Exact behavior: agent-device help reinstall.
agent-device reinstall com.example.app ./build/app.apk --platform androidagent-device reinstall com.example.app ./build/MyApp.app --platform iosreinstall <app> <path>uninstalls and installs in one command, for login/logout resets and deterministic test setup. Device coverage, formats, and remote upload matchinstall.- On iOS and Android, replacement archives are unpacked before the installed app is removed. If unpacking fails, the app and its data stay in place. An Android archive with no
.apkor.aabalso leaves the installed app in place. An invalid app bundle, corrupt APK or another install failure after uninstall can still leave the app removed.
App uninstall
Remove an installed app.
agent-device uninstall <app> [--os <version|range>] [--image-tag <tag>] [--device-mode <slim|full>] [--device-baseline <name>] [--physical]| Option | What it does |
|---|---|
--os <version|range> |
Proxy lease: OS version or range the backend picks the device by (Android: API level); refused without such a backend |
--image-tag <tag> |
Proxy lease: Android system image tag the backend picks the device by; refused without such a backend |
--device-mode <slim|full> |
Proxy lease: iOS simulator mode (slim or full) the backend leases; refused without such a backend |
--device-baseline <name> |
Proxy lease: saved device state (baseline) the backend restores on the leased device; refused without such a backend |
--physical |
Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend |
Supported targets: Uninstall an app.
Exact behavior: agent-device help uninstall.
agent-device uninstall com.example.app --platform androiduninstall <app>removes an installed app, for example to start a test without the app installed. Android (ADB), iOS simulators, CoreDevice iOS devices, and HarmonyOS devices are supported.- On HarmonyOS, success keys on a second
bm dump -nafter the uninstall, becausebmprints its verdict into stdout while exiting zero. - A package name or bundle id that is not installed succeeds with
wasInstalled: false; another name that matches nothing installed fails withAPP_NOT_INSTALLED.
App install from source URL
Install app builds from URLs.
agent-device install-from-source <url>| Option | What it does |
|---|---|
--header <name:value> |
install-from-source: repeatable HTTP header for URL downloads |
--retain-paths |
install-from-source: keep materialized artifact paths after install |
--retention-ms <ms> |
install-from-source: retain files for 1-2147483647 ms |
Supported targets: Install from a source URL.
Exact behavior: agent-device help install-from-source.
agent-device install-from-source https://example.com/builds/app.apk --platform androidagent-device install-from-source https://example.com/builds/app.aab --platform androidinstall-from-source <url>installs an artifact the daemon can reach at a URL; useinstallorreinstallfor local files. Device coverage matchesinstall.install-from-sourceallows 600 seconds overall, including up to 120 seconds for the download. The local Android and iOS install limits matchinstall.- A URL may point to an Android
.apkor.aab, or, from any public host, to an archive containing one.apk,.aab,.ipa, or iOS.app. - Repeat
--header <name:value>for authenticated or signed downloads. Sensitive headers are not forwarded to other origins. --retain-pathskeeps the downloaded and extracted files for 15 minutes. Use--retention-ms <ms>to set an integer duration from 1 to 2,147,483,647 milliseconds.- Limits: at most five redirects, no HTTPS-to-HTTP downgrade, 2 GiB download, 4 GiB extracted, 100,000 entries, and three nested archive layers. Links and special archive entries are rejected.
HTTP_PROXY,HTTPS_PROXY, andNO_PROXYare honored. These match the Node.js client’sinstallFromSource()checks.
Install a GitHub Actions artifact
GitHub gives each artifact a signed download URL. The URL needs no credentials, so the device or remote daemon can fetch the build directly. The URL expires after about one minute, so get it right before the install:
url=$(curl -fsS -o /dev/null -w '%{redirect_url}' \ -H "Authorization: Bearer $(gh auth token)" \ https://api.github.com/repos/<owner>/<repo>/actions/artifacts/<artifact-id>/zip)agent-device install-from-source "$url" --platform androidIn a GitHub Actions job, use ${{ secrets.GITHUB_TOKEN }} instead of gh auth token. The token stays on the machine that runs the command.
Push notification simulation
Deliver a push notification payload.
agent-device push <bundleOrPackage> <payloadOrJson>Supported targets: Push notification simulation.
Exact behavior: agent-device help push.
agent-device push com.example.app ./payload.apns --platform iosagent-device push com.example.app '{"aps":{"alert":"Welcome","badge":1}}' --platform iosagent-device push com.example.app '{"action":"com.example.app.PUSH","extras":{"title":"Welcome","unread":3,"promo":true}}' --platform androidpush <bundle|package> <payload.json|inline-json>simulates push notification delivery to the session device or the one named by--platform,--device,--udid, or--serial.- iOS: simulator only, with an APNs-style JSON object payload.
- A daemon that serves the public remote surface accepts only an inline JSON object payload. It refuses payload file paths with reason
REMOTE_HOST_INPUT_DENIED. - Android: sends a broadcast with the payload
{"action":"<intent-action>","receiver":"<optional component>","extras":{...}}. Extras may be strings, booleans, or numbers.
App event triggers (app hook)
Invoke an app-defined automation event.
agent-device trigger-app-event <event> [payloadJson]Supported targets: App event triggers through the app hook.
Exact behavior: agent-device help trigger-app-event.
agent-device trigger-app-event screenshot_taken '{"source":"qa"}'trigger-app-event <event> [payloadJson]opens your app’s deep-link hook with an app-defined event; it does not post OS-level notifications.payloadJsonmust be a JSON object.- Needs an active session or a device selector (
--platform,--device,--udid,--serial). On iOS physical devices, open the app in the session first. - Set the URL template with
AGENT_DEVICE_APP_EVENT_URL_TEMPLATE, or per platform withAGENT_DEVICE_IOS_APP_EVENT_URL_TEMPLATE,AGENT_DEVICE_MACOS_APP_EVENT_URL_TEMPLATE, orAGENT_DEVICE_ANDROID_APP_EVENT_URL_TEMPLATE. Placeholders are{event},{payload}, and{platform}, for examplemyapp://agent-device/event?name={event}&payload={payload}.
Settings helpers
Change OS settings and app permissions.
agent-device settings <wifi|bluetooth|airplane|mobile-data|location|animations> <on|off> | settings location set <lat> <lon> | settings appearance <light|dark|toggle> | settings text-size [extra-small|small|medium|large|extra-large|extra-extra-large|extra-extra-extra-large|accessibility-medium|accessibility-large|accessibility-extra-large|accessibility-extra-extra-large|accessibility-extra-extra-extra-large] | settings <faceid|touchid> <match|nonmatch|enroll|unenroll> | settings fingerprint <match|nonmatch> | settings clear-app-state [app-id] | settings reset-keychain clear | settings permission <grant|deny|reset> <all|camera|microphone|photos|contacts|contacts-limited|notifications|calendar|location|location-always|media-library|motion|reminders|siri> [full|limited] | settings permission <grant|reset> <accessibility|screen-recording|input-monitoring> [--app <id-or-name>]| Option | What it does |
|---|---|
--app <id-or-name> |
Target an app without opening it: doctor verifies an installed app by id or name; settings applies an app-scoped change (permission, iOS location) to a bundle id or package |
Supported targets: System and app settings helpers.
Exact behavior: agent-device help settings.
agent-device settings wifi onagent-device settings wifi offagent-device settings bluetooth onagent-device settings bluetooth offagent-device settings airplane onagent-device settings airplane offagent-device settings mobile-data offagent-device settings mobile-data onagent-device settings location onagent-device settings location offagent-device settings location set 37.3349 -122.009agent-device settings animations offagent-device settings animations onagent-device settings text-sizeagent-device settings text-size largeagent-device settings text-size accessibility-extra-largeagent-device settings appearance lightagent-device settings appearance darkagent-device settings appearance toggleagent-device settings faceid matchagent-device settings faceid nonmatchagent-device settings faceid enrollagent-device settings faceid unenrollagent-device settings touchid matchagent-device settings touchid nonmatchagent-device settings touchid enrollagent-device settings touchid unenrollagent-device settings fingerprint matchagent-device settings fingerprint nonmatchagent-device settings clear-app-stateagent-device settings clear-app-state com.example.appagent-device settings reset-keychain clearagent-device settings permission grant cameraagent-device settings permission deny microphoneagent-device settings permission grant photos limitedagent-device settings permission reset notificationsagent-device settings permission grant camera --app com.example.appagent-device settings location on --app com.example.appagent-device settings permission grant accessibility --platform macosagent-device settings permission reset screen-recording --platform macosPlatform support:
- iOS
settingsworks on simulators only. - macOS supports only
settings appearance <light|dark|toggle>andsettings permission <grant|reset> <accessibility|screen-recording|input-monitoring>. settings appearancesets macOS appearance, iOS simulator appearance, or Android night mode.settings location set <lat> <lon>sets coordinates on iOS simulators and Android emulators.- A target that does not serve a setting refuses it with
UNSUPPORTED_OPERATIONanderror.details.reason(for exampleunsupported-platform-leaf) before anything changes. A request that names an app the change cannot take is refused first, withINVALID_ARGSandsetting_app_not_consumed.settings --helpdescribes where each setting runs. - On an iOS simulator,
settings wifiandsettings airplanewait for screenshots and other status bar writes. The request timeout includes this wait (90 seconds for a standalone CLI request). Once the write starts, its status bar command has a separate 10-second timeout. A request or write that times out may already have changed the bar; check the bar before relying on it. Cancelling while still queued guarantees nothing was written.
Device settings:
settings animations off|on(Android) sets the window, transition, and animator scales. Turn animations off to stabilize runs with heavy animation, and back on afterward.settings bluetooth on|off(Android over adb) turns the Bluetooth adapter on or off withsvc bluetooth, from Android 8.1. A device or emulator image without a Bluetooth adapter fails withUNSUPPORTED_OPERATIONanderror.details.reason: android_bluetooth_adapter_missingwithout changing anything. A device that has an adapter but runs a build older than Android 8.1 fails the same way withandroid_bluetooth_command_unavailable. It waits up to 2 seconds for the device to hold the requested state and reports it asbluetooth; a change the device refuses, such as one a device policy blocks, fails withCOMMAND_FAILEDanderror.details.reason: bluetooth-not-applied, orbluetooth-unreadableif the final read is not a known state. The app may take longer to react, so poll it rather than asserting immediately.settings airplane on|off(Android) needs the connectivity service’scmd connectivity airplane-modecommand, available from Android 11. It reports the resultingairplaneMode; a build without that command fails withUNSUPPORTED_OPERATIONwithout changing anything. Connectivity takes a moment to settle, so poll the app rather than asserting offline behavior immediately.settings mobile-data on|off(Android over adb) switches mobile data withsvc data enable|disableand reports the resultingmobileDatafrom the globalmobile_datarow. If that row does not settle to the request within 2 seconds, it fails withCOMMAND_FAILED:error.details.reasonismobile-data-unreadableif the final read is neither0nor1, ormobile-data-not-appliedif it is the opposite state. Pair it withsettings wifi offto move a session such as a video stream from Wi-Fi to cellular, and back withsettings wifi on. Poll the app while the network hands over.- The read-back covers single-SIM targets only. A multi-SIM device stores the switch per subscription and can leave
mobile_dataunchanged, so the command may fail there even when the switch took effect. A target without an active SIM can also acceptsvc datawithout changing the row, and with Wi-Fi off it is offline rather than on cellular. - Mobile data and Bluetooth are device-wide, so
--appis refused withsetting_app_not_consumed. Every target without adb refusesmobile-datawithUNSUPPORTED_OPERATIONbefore anything runs. settings text-sizereads the current size;settings text-size <category>sets one:extra-small,small,medium,large,extra-large,extra-extra-large,extra-extra-extra-large,accessibility-medium,accessibility-large,accessibility-extra-large,accessibility-extra-extra-large, oraccessibility-extra-extra-extra-large. It works on iPhone and iPad simulators and on Android; every other target refuses both read and write. The read reportscategoryand the target’s ownplatformValue(iOS may capitalize it, for exampleextra-Small).- Android has only a font-scale multiplier, mapped so
largeis1.0andaccessibility-extra-extra-extra-largeis3.2. A value between rungs reads as the nearest category, with the exact multiplier inplatformValue; an unset scale reads aslarge. - A running app adopts a new text size only at its next configuration change. Relaunch it (
open <app> --relaunch) before asserting rendered sizes.
Biometrics:
faceidandtouchidwork on iPhone and iPad simulators with any Xcode; Apple TV and Vision Pro simulators refuse them.enroll/unenrollchange enrollment.fingerprintworks on Android targets wherecmd fingerprintoradb emu fingeris available; physical devices usecmd fingerprintonly.matchandnonmatchsimulate a valid or invalid Face ID, Touch ID, or fingerprint.
App state:
settings clear-app-state [app-id]clears the data of the session app or the named app (positional or--app, not two different ones). On Android this removes preferences, databases, files, and cache; on iOS simulators it empties the app’s data container. It is unsupported on iOS physical devices and macOS.- It does not touch the keychain, so keychain-backed credentials such as Firebase auth survive.
settings reset-keychain clearresets the iOS simulator keychain for every app on that simulator, not only yours; pair it withclear-app-statefor a fresh-install reset. It is unsupported on iOS physical devices, Android, and macOS. - An app with no data container, such as a simulator’s built-in
com.apple.Preferences, refuses withUNSUPPORTED_OPERATIONanderror.details.reason: app-no-data-container. Built-in apps cannot be uninstalled either; erase or recreate the simulator to reset one.
Permissions:
- On iOS and Android,
permissionand iOS simulatorlocation on|offapply to the session app. Pass--app <bundle-id, package, or name>to target an installed app without opening it, for example to grant a permission before first launch. The app need not be running. Unlikeopen, which passes an unknown id through, settings resolve only installed apps, the same wayclear-app-statedoes. On an iOS simulator, including Limrun, a dotted name is first matched against installed bundle ids, and any name against installed display names (--app Mapsiscom.apple.Maps). On Android, a package must be installed, and any other name is matched against installed package names. --appcounts only when passed on the command line;AGENT_DEVICE_TARGET_APPandtargetAppin~/.agent-device/config.jsonnever retarget a settings change.- Refusals for
permission,location, andclear-app-state, all withdispatched: noand nothing changed:app_not_installed(APP_NOT_INSTALLED): the app resolves to nothing installed.session_app_required: no session app and none named. Runopen <app>, or name the app.setting_app_not_package(INVALID_ARGS, Android): the name is an intent alias such assettings, not a package.setting_app_not_consumed: the change is device-wide and cannot take an app:location set, the Androidlocation on|offtoggle, macOS permissions,mobile-data, andbluetooth.
- iOS targets:
all,camera,microphone,photos(fullorlimited),contacts,contacts-limited,notifications,calendar,location,location-always,media-library,motion,reminders,siri. The simulator decides which it can change; one it refuses fails withUNSUPPORTED_OPERATIONnaming it. On current runtimes that isnotifications.grant allanddeny allchange each service in turn, withcontactsandphotosin full andlocation-always;deny allalso revokes limited photos (photos-add). They report the changed services inpermissions, add aSkipped <service>entry towarningsfor each service the simulator refuses, and on any other failure stop with the services already changed inerror.details.permissions.reset allclears every service in one call. - Android targets:
all,calendar,camera,contacts,location,media-library,microphone,notifications,photos. Targets covering several permissions apply only the ones the app declares and fail if it declares none;allapplies every declared permission, and on an app that declares none changes nothing, with a warning. The response reportspermission(what you asked for) andpermissions(what was changed). - macOS targets:
accessibility,screen-recording,input-monitoring.grantchecks or requests access and opens System Settings when needed; it never grants silently.denyis unsupported. full|limitedapplies only to iOSphotos.- Android
resetrevokes. Changes apply to the device’s foreground user; if it cannot be determined, the command fails withCOMMAND_FAILEDand changes nothing. - Android kills a running app when one of its granted permissions is revoked.
denyandresetreportpriorGrantState(granted,not_granted, orunknown) and warn you to runopen <app> --relaunchunless it wasnot_granted.
App state and app lists
Show the foreground app and activity.
agent-device appstateSupported targets: Foreground app state.
Exact behavior: agent-device help appstate.
List installed apps or deferred provider app assets.
agent-device apps [--all]| Option | What it does |
|---|---|
--all |
Apps: include system/OEM apps |
Supported targets: Installed app list.
Exact behavior: agent-device help apps.
agent-device appstateagent-device apps --platform iosagent-device apps --platform ios --allagent-device apps --platform androidagent-device apps --platform android --all- Android and HarmonyOS
appstatereport the live foreground package and activity. - iOS and macOS
appstateneed a session and report that session’s app:appName,appBundleId, and asource. On iOS, when a live runner answers the read, the answer carries itsstate(runningForeground,runningBackground,runningBackgroundSuspended,notRunning, orunknown) withsource: runner. They never start a runner; when none is running they reportsource: sessionand nostate, and on macOS the answer is always session-scoped. When the read fails, for example because the runner cannot reply right now,appstatefails instead of answering from the session. Limrun iOS uses the same live XCTest runner read. Without a live runner, it returnssource: sessiononly after the instance responds; when the instance cannot be confirmed it fails with reasonlimrun_instance_unreachable. Any provider whose session has ended refusesappstatewith reasonowner-capability-missing. On iOS, afterhomethe app reports a background state; which app took the screen is not reported. A command that had to bring the app back reports atargetActivationdisclosure. appsshows user-installed apps. Add--allto include system and OEM apps.
Foreground repairs on iOS
An iOS session is bound to one app, but a deep link, a system sheet, or simctl openurl can hand the
screen to another app. The next command brings the session app back so it can answer, and reports
that repair:
agent-device open com.example.app --platform iosagent-device screenshot --platform ios # Safari screenagent-device snapshot -i --platform ios # answers with the app's treeThe snapshot response carries targetActivation and a warning:
{ "targetActivation": { "reason": "bundle_changed", "priorState": "runningBackground", "otherActiveApplicationPid": 4562 }}- Anything captured earlier in the session described the other app. Capture again, or drive the other app in its own session.
reasonnames the check that caught it:bundle_changed(the runner’s cached target differs from the requested bundle),stale_target(the cached target no longer answers as foreground),missing_after_wait(a wait never saw the app), orinteraction_foreground_guard(an interaction’s guard tripped before dispatch).priorStateis the app’s state before the repair; it is neverrunningForeground.otherActiveApplicationPidappears only when exactly one other app held an accessibility session. It does not prove that app owned the screen, and its absence is not a failure.snapshot,find,get,is,wait, and interactions that captured a tree report it at every--level, includingdigest; on failure it is inerror.detailsand the hint. In text mode it prints as aWarning:line after any earlier warnings; see Output and warnings. Reads answered from a cached tree did no repair and report none.- Silence is not proof. A coordinate
press, apress @refanswered from a live ref frame, or await <text>satisfied on its first poll may re-activate the app without saying so. When it matters, runsnapshot -iand read its disclosure (#2694). - A coordinate
presson a system surface runs in place. While the session app is in the background, apress <x> <y>on a point that SpringBoard owns (a notification banner, the Home Screen, Control Center) reaches that point and does not bring the app back. A point over another app still brings the session app back first. - No read launches a stopped app.
snapshot,wait,is,get, a readingfind, and the leading read ofgestureor a selectorclick/fillbring a backgrounded app forward but never start one that is not running, because a launch could drop a URL waiting behind an “Open in …?” prompt. They fail withCOMMAND_FAILED,details.runnerErrorCode: "APP_NOT_RUNNING", andretriable: true;waitkeeps polling. Answer the prompt withalert accept, or relaunch withopen. Commands that act without reading first (press, coordinatefill,swipe,scroll, hardware keys) still start a stopped app.
Clipboard
Read or write device clipboard text.
agent-device clipboard read | clipboard write <text>Supported targets: Clipboard read and write.
Exact behavior: agent-device help clipboard.
agent-device clipboard write "" # clear clipboardThings to know:
- Treat
clipboard readoutput as sensitive. It can contain copied secrets. - The command works without a session when you pass a device selector (
--platform,--device,--udid,--serial). - iOS physical devices return
UNSUPPORTED_OPERATION. Android 16 (API 36) does too, andcapabilitiesomitsclipboardthere; see Known limitations.
Keyboard
Inspect, press, or dismiss the device keyboard.
agent-device keyboard [status|get|dismiss|enter|return]Supported targets: Keyboard dismiss, enter, and status.
Exact behavior: agent-device help keyboard.
Things to know:
keyboard status(aliaskeyboard get) reports whether the software keyboard is visible. When it can identify the Return key, it reports the key’s action asreturnKey. A value ofunknownmeans that the keyboard is visible but the action could not be identified. On iOS,OBSERVATION_UNAVAILABLEmeans that the runner could not establish visibility.keyboard enter(aliaskeyboard return) sends Return to the focused input, so focus the intended field first. The app decides what Return does: submit, advance focus, or insert a newline. It can work with the software keyboard hidden.- On iOS,
keyboard dismissdoes not close a visible keyboard. It returnskeyboard_dismiss_unavailablewithdispatched: no. Press the visible Hide Keyboard key or the app control that ends editing. If the app supports interactive dismissal, drag down from inside the scrollable content withgesture pan x y 0 dy durationMsand a positivedy. Check the result withkeyboard status. - On Android,
keyboard dismissasks the platform to close the keyboard. If the keyboard stays up, it returnskeyboard_dismiss_unavailable.
Performance diagnostics
agent-device perf frames --jsonagent-device perf memory sample --jsonagent-device perf memory snapshot --kind android-hprof --out app.hprofagent-device perf memory snapshot --kind memgraph --out app.memgraphagent-device cdp target list --url http://127.0.0.1:8081agent-device cdp memory usage sample --label baseline --gcagent-device cdp memory snapshot capture --name baseline --gcagent-device perf cpu profile start --kind xctrace --template "Time Profiler" --out app.traceagent-device perf cpu profile stop --kind xctrace --out app.traceagent-device perf cpu profile report --kind xctrace --out app-profile.jsonagent-device perf trace start --kind xctrace --template "Animation Hitches" --out hitches.traceagent-device perf trace stop --kind xctrace --out hitches.traceagent-device perf cpu profile start --kind simpleperf --out cpu.perf.dataagent-device perf cpu profile stop --kind simpleperf --out cpu.perf.dataagent-device perf cpu profile report --kind simpleperf --out cpu-report.jsonagent-device perf trace start --kind perfetto --out app.perfetto-traceagent-device perf trace stop --kind perfetto --out app.perfetto-trace- Name one area:
frames,memory,cpu, ortrace. Bareperf,perf sample,perf metrics, and themetricsalias fail with guidance to the focused replacements. perf framesreturns frame/jank health (droppedFramePercent,worstWindows).perf memory samplereturns a compact process memory sample in kilobytes.perf memory snapshotwrites a heap or memgraph artifact and returns its path.perf cpu profileandperf tracerecord Apple (--kind xctrace) or Android (--kind simpleperf,--kind perfetto) profiles and traces, and return artifact paths plus compact metadata; raw contents stay on disk.cdpsamples and snapshots the React Native JavaScript heap through Metro CDP; see Debugging and profiling.- App startup duration is returned in
open’sstartupresult. - Perf commands need an app session with a package or bundle ID; run
open <app>first. - Platform support:
perf frames: Android emulators and devices, and connected iOS devices. iOS simulators and macOS report it unavailable because Apple tooling exposes no trustworthy hitch data there.perf memory sample: Android, HarmonyOS devices, iOS simulators and devices, and macOS.perf memory snapshot --kind android-hprof: Android, for a running debuggable or profileable process that permits heap dumps.--kind memgraph: iOS simulators and macOS; physical iOS devices report it unavailable with a recovery hint. Native heap tracing (perf memory trace --kind heapprofd) is not available.--kind xctrace: iOS simulators, connected iOS devices where xctrace can attach to the app process, and macOS when the app process resolves from the bundle ID (forperf trace, when the template supports the target). It does not profile Android.--kind simpleperfand--kind perfetto: Android app sessions with a running package process only.- HarmonyOS is memory-only: CPU profiling, frame sampling, and memory snapshots are unavailable.
For the measurement workflow, data sources, and output examples, see Performance snapshots.
React Native components
agent-device react-devtools tree [@ref|Name] [--depth 8] [--limit 60]agent-device react-devtools find <Name> [--exact] [--limit 20]agent-device react-devtools inspect <@ref|Name>agent-device react-devtools errors [--limit 10]treeprints the mounted component tree with@crefs. A chain of single-child wrappers, such as providers, prints on one line. Three or more consecutive siblings whose subtrees match exactly, in names, types, and logged errors and warnings, print as one counted line; other siblings, including same-name screens with different contents, keep their own lines. Pass a ref or a unique name to print one branch.findlists components whose name contains the text, ignoring case, or equals it with--exact, each with the components that rendered it.inspectprints a component’s owners, props, state, hooks, and the errors and warnings it logged while rendering. It takes a ref, or a name only one mounted component has.errorslists the components that logged console errors or warnings while rendering, with the messages. When the app’s React DevTools backend does not attribute every log to a component, as on React Native 0.74 and 0.76, it says the list can be incomplete.- These commands connect the same way as profiling, below. A connected React DevTools window owns the component tree, so
tree,find, anderrorsfail withtree-unavailableuntil it is closed and the app reloads.
React Native performance profiling
agent-device react-devtools profile startagent-device react-devtools profile stopagent-device react-devtools profile stop --limit 10agent-device react-devtools profile reportagent-device react-devtools profile report <Component>agent-device react-devtools profile commitagent-device react-devtools profile commit <N>profile startbegins recording React renders in the app;profile stopends it and prints the commit count, render time, commits over the 16 ms frame budget, and up to five findings (--limitchanges that). It also saves the recording for the session, soreportandcommitread it without the app.profile reportlists components by self time with why they rendered;profile report <Component>shows every component of that name, such asRowand memoizedRow, each with its causes, changed props, owners, costliest commits, and findings.profile commitlists commits in order, or the slowest ones in order when there are more than--limit(default 20);profile commit <N>shows what rendered in one commit.--limitcaps the rows of the list views.- Profiling connects through the app’s Metro dev server and needs no app or Metro setup. It works with development builds of React Native 0.74 and later on Android emulators, iOS simulators,
agent-device proxyconnections, and remote bridge sessions. On a remote bridge it uses the Metro server next to the agent: the session’s binding frommetro prepare, or--metro-host/--metro-port. Metro accepts the debugger connection only from its own machine, so the bridge ormetroPublicBaseUrlcannot carry it. --app <bundle-id>picks the app when several share the dev server, and--metro-device <name>picks the device when one app runs on several.--metro-portand--metro-host, or--bundle-urlfor a dev server behind a URL path, pick the dev server when it is neither the session’s Metro server norlocalhost:8081.- With
--json,profile stopreturns the findings and the path of the saved profile. - See Debugging and profiling for the findings and the workflow.
React Native overlays
agent-device react-native dismiss-overlayagent-device react-native dismiss-overlay --platform androidreact-native dismiss-overlayclears a development overlay (redbox/LogBox error or collapsed warning banner) that blocks interaction, and is a no-op when none is present. It works on iOS simulators/devices and Android emulators/devices, and is the onlyreact-nativesubcommand.
Multiple React Native worktrees
You can reuse one installed iOS simulator debug build across local worktrees when its native binary is compatible with both JavaScript trees. Run one Metro server per worktree on its own port, then open the app on different simulators with explicit Metro hints:
# Worktree A terminalyarn expo start --dev-client --port 8081 --host localhost
# Worktree B terminalyarn expo start --dev-client --port 8082 --host localhost
agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081 --relaunchagent-device open "React Navigation Example" --platform ios --device "iPhone 17 Pro" --session rn-b --metro-host 127.0.0.1 --metro-port 8082 --relaunch- Use a different simulator and session per worktree; one simulator cannot run two copies of the same bundle id.
- On iOS simulators,
openwrites React Native’s per-simulator debug server settings before launch. Expo dev clients ignore those settings, so when the app registers a singleexp+<slug>URL scheme,openlaunchesexp+<slug>://expo-development-client/?url=<server>instead; if the scheme check is inconclusive, the app opens normally.--launch-urloverrides this. A dev build that boots straight into its embedded bundle still needs a native rebuild. - Each session remembers its dev server for a flagless
metro reload --session <name>; see Metro reload. - This covers JavaScript and Metro-resolved changes. Rebuild and reinstall when native code, native dependencies, bundle identifiers, entitlements, or generated native project files change.
- Close every session when done:
agent-device close --platform ios --session rn-aagent-device close --platform ios --session rn-bMetro reload
agent-device metro reloadagent-device metro reload --metro-host localhost --metro-port 8081agent-device metro reload --bundle-url "http://localhost:8081/index.bundle?platform=ios"metro reloadasks connected React Native dev builds to reload JavaScript without restarting the native process, like pressingrin the Metro terminal.- The target server comes from per-call flags first, then the dev server the session last bound through
metro prepareoropen’s--metro-host/--metro-port/--bundle-url, thenhttp://localhost:8081/reload. A host or port flag overrides only that field. A reused session name never reloads a previous project’s server:closeclears the binding, and so does a freshopenwithout Metro hints. Aftermetro prepare, reload uses the local server address even when the device loads through a public or proxy URL. - A bundle URL keeps its mount prefix:
http://host/tenant-42/.expo/.virtual-metro-entry.bundlereloadshttp://host/tenant-42/reload. - When the server has no HTTP
/reloadroute (Expo), the reload is broadcast over the server’s/messagewebsocket. The result’stransportfield says which channel delivered it. - Use
open <app> --relaunchinstead when the app is not connected to Metro, reload fails, or the native process must restart. Seeagent-device help metrofor the full binding rules.
Media and logs
agent-device screenshot # Auto filenameagent-device screenshot page.png # Explicit screenshot pathagent-device screenshot page.png --scale 0.3 # Resize both dimensions to 30% for agent contextagent-device screenshot page.png --overlay-refs # Draw current @eN refs and target rectangles onto the PNGagent-device screenshot page.png --crop-on 'label="Save"' # Crop the capture to the frame the selector resolves on the same screenagent-device screenshot baseline.png --normalize-status-bar # Normalize iOS simulator or ADB-backed Android chrome for reusable diff baselinesagent-device screenshot baseline.png --screen-mask black --normalize-status-bar # Capture an iOS simulator baseline with a black screen outlineagent-device screenshot page.png --capture-backend runner # Apple: capture through the XCTest runner (no simulator-drawn Dynamic Island)agent-device screenshot page.png --platform web --fullscreen # On web, --fullscreen/--full/-f captures the entire documentagent-device viewport 1280 900 --platform web # Resize the active web viewport for fixed-layout or 100vh appsagent-device screenshot textedit.png # App-session window capture on macOSagent-device screenshot --fullscreen # Force full-screen capture on macOS app sessionsagent-device open --platform macos --surface desktop && agent-device screenshot desktop.pngagent-device diff screenshot --baseline baseline.png --out diff.pngagent-device diff screenshot --baseline baseline.png current.png --out diff.pngagent-device diff screenshot --baseline baseline.jpg --out diff.png # JPEG inputs are accepted tooagent-device diff screenshot --baseline baseline.png --out diff.png --overlay-refsagent-device record start # Start app-scoped recording after open <app>agent-device record start session.mp4 # Start app-scoped recording to explicit pathagent-device record start session.mp4 --scope device # Intentionally record the full simulator/device screenagent-device record start session.mp4 --fps 15 # Runner capture rate and touch-overlay frame capagent-device record start session.mp4 --quality high # Higher-quality export (slower)agent-device record stop # Stop active recordingScreenshots
--scale <factor>resizes both dimensions, from0.01to1(full resolution). SetAGENT_DEVICE_SCREENSHOT_SCALE=0.3orscreenshotScalein config as a token-conscious default; an explicit--scaleoverrides it. Leave it unset or pass--scale 1for pixel-diff baselines.--max-sizeis refused everywhere (CLI,.adscripts, Node options, config,AGENT_DEVICE_SCREENSHOT_MAX_SIZE) with guidance to use--scale.- ADB-backed Android screenshots capture immediately by default. Use
--normalize-status-barto set deterministic status-bar chrome and wait for transient UI to fade. In the Node client,stabilize: truealso enables this wait. --overlay-refstakes a fresh snapshot and burns visible@eNrefs and their rectangles into the PNG. With--scale, refs are drawn at the final size, so avoid scales where labels become unreadable. In--jsonmode each ref also has a screenshot-spacecenterforpress <x> <y>fallback.--crop-on <selector>crops the capture to the frame the selector resolves on the same screen. It works only on iOS simulators, Android emulators, physical iPhones, and the Samsung Tizen and LG webOS TV plugins. A physical iPhone crop is verified only in portrait using CoreDevice/devicectl; the XCTest backend and runner fallback are not accepted. Physical iPads remain rejected for crop, and landscape iPhone crop remains unverified. It needs exactly one framed node, cannot be combined with--overlay-refsor--fullscreen, and warns when the frame is clipped. The crop is re-encoded, so do not byte-compare it with an older crop.--fullscreenon macOS applies only to app sessions. Other surfaces (desktop,menubar,frontmost-app) always capture the main display and refuse--fullscreenwithINVALID_ARGS.--capture-backend runnercaptures an Apple target through the XCTest runner (XCUIScreen), as XCTest-based tools such as Maestro do, instead ofsimctl io screenshot. On iOS simulators with a Dynamic Island,simctldraws the island into every capture and no--maskpolicy removes it; the runner capture leaves it out. The capture skips the simctl pipeline, so--pixel-densityand--normalize-status-barare refused with it (INVALID_ARGS). Each capture owner declares the backends it serves: other platforms, provider-backed sessions, and macOS surfaces the helper captures (desktop,menubar,frontmost-app, and app sessions with the native app backend) refuse it withUNSUPPORTED_OPERATION. Node and MCP takecaptureBackend: 'runner'.--normalize-status-bartemporarily normalizes iOS simulator status-bar chrome for reusable baselines. Each status-bar read or preparation command has a 10-second timeout. Each restore command has a 30-second timeout, so clearing and reapplying overrides can take up to 60 seconds. The request timeout includes the wait and can expire before these steps finish.--screen-mask blackfills the iOS simulator screen outline, including rounded corners, with black for this capture. Node and MCP usescreenMask: "black". Omit it for the default image. Support is limited to handheld iOS/iPadOS simulators. It requires simctl capture; physical devices, tvOS and visionOS simulators, other platforms, provider captures, and XCTest runner captures are refused. If simctl fails, a masked request fails instead of falling back to an unmasked runner capture. This option does not redact app content, remove a Dynamic Island drawn into the framebuffer, or change comparison thresholds.- On an iOS simulator, a screenshot waits until no other screenshot or
settings wifi/settings airplanewrite is using that simulator’s status bar, so overlapping captures cannot see each other’s temporary chrome. A request you cancel while it is waiting fails with the cancellation instead of capturing. - On single-display iOS simulators and Android devices, the result may report
displayRotation(portrait,portrait-upside-down,landscape-left, orlandscape-right). It is absent when the device returns no reading in time, on other targets, and on multi-display devices such as foldables. The saved image is always upright.
Screenshot diffs
diff screenshotcompares a live capture, or a savedcurrent.png(no session needed), against--baseline. Inputs may be PNG or JPEG regardless of extension; HarmonyOS captures are JPEG. Output ranks changed regions with rectangles, changed-pixel counts, and share of the diff;--outwrites a diff PNG with changed pixels tinted red.ocrandnonTextDeltasare never populated, so read the images yourself for qualitative review.--threshold <0-1>sets the per-pixel RGB tolerance (default0.1). Keep it above0when either input is JPEG.- The current image scales proportionally to the baseline width and aligns at the top left. Its scaled height rounds to the nearest pixel, with a minimum of one row. The comparison includes the full height of both images: extra or missing bottom rows count as differences, including blank or transparent rows, even at
--threshold 1. Your original files stay unchanged. This does not crop system bars or move content into alignment. - When dimensions differ, JSON
normalizationreportsbaseline,current,scaledCurrent, andcompareddimensions.currentScale.xand.ymap original current pixels to comparison pixels; the height scale includes pixel rounding. Region rectangles and ref-match rectangles use comparison pixels, and normalized region rectangles use percentages of the compared canvas. The separate current-screen overlay keeps its original capture size. --overlay-refsalso writes a separate current-screen ref overlay and lists refs under changed regions. It needs a live capture, so it is unavailable with a savedcurrent.png.- Live iOS simulator diffs normalize status-bar chrome by default. Use
diff screenshot --baseline baseline.png --screen-mask blackto apply the same screen outline as a baseline captured withscreenshot --screen-mask black. The mask affects only this live capture, including its optional ref overlay. It is refused with a saved current image ordiff snapshot; saved-image comparisons do not apply a mask.
Recordings
record startdefaults to app scope and needs a session fromopen <app>. Use--scope deviceor--scope systemfor whole-screen capture (multiple apps, settings, home screen) where the backend supports it.- iOS recording works on simulators and CoreDevice-backed physical devices. Physical devices capture runner screenshots, not a native video stream: no audio, dropped frames are expected, and the default is 15 FPS.
--fps <n>(1-120) caps the rate; a busy app or long command yields fewer frames. --quality medium|high(defaultmedium) sets export quality on Android and Limrun; Apple export always keeps the captured resolution. Numeric5-7map tomediumand8-10tohigh.- With touch visualization on, recordings also produce a gesture telemetry sidecar. Burned-in touch overlays export only on macOS hosts; elsewhere
record stopreturns the raw video and telemetry withoverlayWarning. The overlay renders at most 30 FPS (or--fpsif lower) within a fixed budget, which also covers the video checks that run before and after it; an export past the budget returns the raw video withoverlayWarning. On a host that has not run a recording before, part of that budget goes to one-time tool setup, so the firstrecord stopof a long recording is more likely to return the raw video. - Android uses
adb shell screenrecord(180s limit per clip). Longer recordings are split into MP4 chunks while the daemon stays alive; after a daemon restart,record stoprecovers only chunks listed in the device manifest. A clip can end beforerecord stopwhen the screen stopped changing;durationMsis wall-clock time, andcapturedDurationMsplus a warning report how much the video covers. Stopping an already exited recorder still collects its completed video. - An Android recorder the device refuses, either at startup or before it writes a first frame, returns
details.reason: android_screenrecord_startup_failed, anddetails.stderrcarries the message the native recorder printed, for examplePermission denied. That message is the device’s own verdict on its recording policy, so report it to the device manufacturer. agent-device has no alternative Android recording backend. - Limrun sessions always record the whole screen and refuse
--fpsand--hide-toucheswithINVALID_ARGS. A failed download is retried by the nextrecord stop; nothing survives a daemon restart. - A busy iOS simulator recording slot returns non-retriable
DEVICE_IN_USEwithdetails.reason: apple_simulator_recording_busy. Runrecord stopin the session that owns the recording; if no recording is active, ask the host operator to restart the CoreSimulator stream service. - MP4 verification setup runs in the background from
record start; capture does not wait for it. If setup exceeds the stop budget, stop returns retriabledetails.reason: video_validator_compile_timeout. Runrecord stopagain; setup continues and your recording is retained. Hosts without xcrun keep container-only MP4 completion. Other compilation failures, or an unavailable validator executable or AVFoundation during verification, returndetails.reason: video_validator_unavailable. Repair the reported failure and retryrecord stop; a failed compile is retried on the next start or stop. record stopis safe to repeat. If the request window ends during export, a secondrecord stopin the same session returns the finished recording. A recording whose video file is gone reportsno active recording.record start --scope deviceon a session that does not exist yet creates one, andrecord stopends that session. If anything else takes over the session meanwhile — anopenor an app event that publishes an app, or an audio probe, perf capture, trace, app log, device claim, or lease it holds —record stopends only the recording; the session stays andclosereleases it.- On a remote daemon, if a leased session ends while a recording runs (lease expiry, release, or
close), the daemon finishes the recording. It keeps the video and telemetry downloadable by the lease’s tenant:GET /artifactslists them withsessionName, andGET /artifacts/<id>downloads them. Each file is deleted after its download, or after 15 minutes. record stopmay also reportrecorder(confirmedorlost) andnativePathDisposition(retirableorretired). Seeagent-device help recordand ADR 0024.record contact-sheet <video.mp4> [--out <sheet.png>]turns an exported MP4 into one PNG grid of the frames where the screen visibly changed, each labeled with its elapsed time. It needs no session or device. The default output is<recording>.contact-sheet.png, and--outcannot point at the recording itself.--jsonadds per-cell times and change shares plussampledFrameCount,decodedFrameCount, andskippedSampleCount.- A contact sheet samples at most 48 times across the clip (every 250ms for short clips) and prints at most 24 cells, so a transient between samples can be missing;
warningsays when cells were thinned or samples skipped. It runs only on macOS hosts (details.reason: contact_sheet_unsupported_hostelsewhere) and refuses WebM withcontact_sheet_container_unsupported.
Session app logs: See Debugging and profiling for the clean-repro and grep workflow.
agent-device logs path # Print session log file path (e.g. ~/.agent-device/sessions/default/app.log)agent-device logs start # Start streaming app stdout/stderr to that file (requires open first)agent-device logs stop # Stop streamingagent-device logs clear # Truncate app.log + remove rotated app.log.N files (requires stopped stream)agent-device logs clear --restart # Stop stream, clear log files, and start streaming againagent-device logs doctor # Show logs backend/tool checks and readiness hintsagent-device logs mark "before submit" # Insert timeline marker into app.logagent-device events # Print recent session request/action eventsagent-device events 50 100 # Page 50 events starting at cursor 100agent-device network dump 25 # Parse recent HTTP(s) requests (method/url/status)agent-device network dump 25 --include all # Include parsed headers/body when available (truncated)agent-device network dump 25 --include headers --platform web # Browser requests via managed agent-browserlogsworks on iOS simulators, iOS physical devices, Android, and macOS (app-scoped Unified Logging). On iOS, capture relies on Unified Logging (os_log); plain stdout/stderr may be limited.- On iOS physical devices,
logs startrelaunches the session app throughdevicectl device process launch --console --terminate-existingand reportsrelaunched: true;logs stopends the app. Runopen <app>again afterlogs stopto keep using it. Other targets do not reportrelaunched. logs startappends toapp.logand rotates at 5 MB. Override withAGENT_DEVICE_APP_LOG_MAX_BYTESandAGENT_DEVICE_APP_LOG_MAX_FILES; setAGENT_DEVICE_APP_LOG_REDACT_PATTERNSto a comma-separated regex list for write-time redaction. Commas inside a{m,n}quantifier,[...], or(...)stay in their pattern; write\,for any other literal comma. If a pattern does not compile,logs startfails withINVALID_ARGS,details.reason: "app_log_redact_pattern_invalid", and the zero-baseddetails.patternIndexof that comma-separated field (empty fields count); the pattern text is not echoed. On Apple simulators,logs startreturns once the simulator log stream is running, so lines that the app logs after that are captured. If the stream does not start within 10 s,logs startfails withdetails.reason: "simulator-log-stream-launch-timeout".openprintsSession state: <path>; see Sessions for the files it contains.eventsreads the session timeline, which leaves out user-entered content;--no-recordsuppressesaction.recordedentries.events.ndjsonrotates before an entry would exceed 5 MiB (AGENT_DEVICE_EVENT_LOG_MAX_BYTES) and keeps one generation. Cursors stay valid across rotation; a cursor older than the retained window fails withdetails.reason: "EVENT_LOG_CURSOR_EXPIRED"anddetails.earliestCursor. If the retained files were edited or deleted,eventsfails withdetails.reason: "EVENT_LOG_WINDOW_UNVERIFIED".- Events are best effort: a line over the file cap or 16 MiB is dropped. An event that would exceed a session’s pending or in-flight limit of 128 events or 16 MiB is also dropped. The command can still succeed. Use
--debugto capturesession_event_log_write_faileddiagnostics for drops and write failures; see Sessions. Failed entries are not replayed. network dump [limit] [summary|headers|body|all]parses recent HTTP(s) entries fromapp.log, or from managedagent-browserrequest history on web;network logis an alias. Prefer--includeover the positional detail level. It scans up to 4000 log lines, returns up to 200 entries, and truncates fields at 2048 characters. Web does not expose bodies.- On iOS,
network dumpcan miss requests the app does not log and cannot name every request on a reused connection, so treat a missing endpoint as unproven. See Network inspection for per-platform behavior.
Crash symbols: debug symbols symbolicates an Apple crash artifact against local dSYMs, writes the symbolicated artifact to --out, and prints a compact crash report. See Crash symbolication.
agent-device debug symbols --artifact crash.log --dsym MyApp.dSYM --out crash-symbolicated.logagent-device debug symbols --artifact crash.ips --search-path ./build --out crash-symbolicated.ipsTracing
agent-device trace startagent-device trace start session.traceagent-device trace stopagent-device trace stop session.tracetrace start [path]begins trace-log capture for the active session;trace stop [path]stops it and writes or finalizes the artifact at that path.- Use
tracefor lower-level session diagnostics thanrecordorlogsprovide.
Remote Metro workflow
When the cloud control plane owns the connection profile, connect discovers it. Name the session once, because every command on a cloud connection must name it:
export AGENT_DEVICE_SESSION=checkout-iosagent-device connectagent-device open com.example.myapp --relaunchagent-device snapshot -iagent-device disconnectFor local profile files, create an agent-device.remote.json:
{ "daemonBaseUrl": "https://bridge.example.com/agent-device", "daemonTransport": "http", "tenant": "acme", "runId": "run-123", "session": "adc-ios", "sessionIsolation": "tenant", "platform": "ios", "leaseBackend": "ios-instance", "metroProjectRoot": ".", "metroProxyBaseUrl": "https://bridge.example.com"}agent-device connect --remote-config ./agent-device.remote.jsonagent-device open com.example.myapp --relaunchagent-device snapshot -iagent-device disconnectFor self-contained scripts, pass the same profile to each step:
agent-device install-from-source https://example.com/builds/Demo.app.zip --remote-config ./agent-device.remote.json --platform iosagent-device open com.example.myapp --remote-config ./agent-device.remote.json --relaunchagent-device snapshot --remote-config ./agent-device.remote.json -iagent-device disconnect --remote-config ./agent-device.remote.jsonconnectfetches the cloud connection profile;connect --remote-config <path>uses a local profile with the host, tenant/run, and optional session, platform, lease backend, and Metro settings. Both save connection state and defer the device lease and Metro preparation until a command needs them (including abatchstep that opens an app). Direct-provider profiles need their provider credentials whenconnectruns. Cloud profiles must be a JSON object atconnection.remoteConfigProfile; the olderconnection.remoteConfigstring is rejected.- Cloud auth:
connectrefreshes a stored CLI session into a short-livedadc_agent_...token. Without a session, interactive shells start login; CI and non-interactive shells fail with API-token setup instructions.--no-logindisables implicit login. Useadc_live_...service tokens for CI. Manage the CLI session withagent-device auth status,auth login, andauth logout; login never stores anadc_live_...token. AGENT_DEVICE_CLOUD_BASE_URLis the bridge/control-plane API origin, not necessarily the dashboard; its/api-keysroute may redirect to the dashboard.- Every command that takes a session on a connection with a lease provider (the cloud,
connect proxy, a device cloud, or aleaseProviderin the profile), includingconnect, must name it with--session,AGENT_DEVICE_SESSION, or config, or it fails withREMOTE_SESSION_REQUIRED. Each session on such a profile leases under its own client and run, derived from the session name, unless the profile names a lease the host issued. For any other profile,connectwithout--sessioncreates a fresh remote session and prints the generated--session, and commands without one fall back to the most recent connection on the machine, which is safe only for one sequential workflow. To replace a connection, pass--session <name> --force. - After
connect, normal commands (install-from-source,open,snapshot,press,screenshot, and others) reuse the connection state.connection statusshowsleaseId=pendinguntil the first platform-bound command allocates the lease. Explicit flags override connected defaults;openwith explicit remote flags but no saved runtime hints warns that React Native apps may launch without Metro hints. - End with
disconnect(ordisconnect --remote-config <path>) to release the lease and stop the Metro companion owned by the connection. It also removes the profile thatconnect <provider>generated, once no other session uses it. It does not stop your Metro server. - If
disconnectcannot release the lease, it still removes the local connection state and prints the lease id, tenant, run, and the configured endpoint when available, so you can release the lease manually. It also keeps the generated profile.disconnect --jsonreports this case asleaseIdandreleaseError. metroProxyBaseUrlis the bridge origin; do not add/api/metro/...paths. The bridge supplies iOS wildcard HTTPS hints and Android runtime routes.metroPublicBaseUrlis only needed for direct, non-bridge bundle hints.metro prepare --remote-config ...is an inspection/debug path that can write--runtime-file <path>.
Session inspection
agent-device session listagent-device session list --jsonsession listshows active daemon sessions for your workspace, or for the named session scope when--sessionorAGENT_DEVICE_SESSIONis set. Add--jsonfor raw session metadata.- A session entry reports
kind,modelandosVersionbeside itsplatformanddevicewhen the host reported them, the way Device discovery describes. It omits a field nothing reported, so a missingosVersionis expected rather than a fault.session list --jsonprints these fields flat: readsessions[0].osVersion, notsessions[0].device.osVersion, which is the device name. The SDK reports the same fields onsession.device, and omits them the same way.
Cloud provider artifacts
agent-device artifacts --provider browserstack --provider-session <webdriver-session-id> --jsonagent-device artifacts --provider aws-device-farm --provider-session <remote-access-session-arn> --jsonartifactslists the provider-hosted artifacts your provider returns, such as videos, logs, and dashboard links, ascloudArtifacts(what each provider returns: Device clouds), separate from the localartifactsthat screenshot, record, install, and replay return. Plain text prints ready URLs.- Looking up a past session needs
--provider-session <id>and--provider <name>. For credentials, see Device clouds. AWS Device Farm infers the region from the session ARN when possible. When an embedding host registers the cloud runtime in-process,artifactsinfers the active provider session before disconnect. disconnect --jsonandclose --jsoninclude provider release data when the runtime returns final artifacts. Providers may finalize URLs only after the session stops, so retryartifactsif the first response ispending.
iOS physical-device prerequisites
For CLI-discoverable setup guidance, run agent-device help physical-device.
- Older devices discovered only through
xctraceuse the XCTest backend automatically; its runner commands travel through macOSusbmuxd, so keep the device connected by cable. - XCTest-backed devices support open/close, interactions, snapshots, and screenshots. App inventory, install/reinstall, logs, performance sampling, recording, deep links, and launch arguments require CoreDevice.
- For Xcode, pairing, Developer Mode, and Apple runner signing, see Installation.
iOS SpringBoard, widgets, and system-UI surfaces
For CLI-discoverable workflow guidance, run agent-device help ios-system-ui.
agent-device open com.apple.springboard --platform iosbinds the session to SpringBoard on iOS simulators and physical iPhones. On a physical iPhone,snapshot -iand selector presses on visible home-screen icons are verified; the widget add/edit/remove flow below is verified on simulators only (see #1296).- The full widget add/edit/remove flow is selector-driven from a fresh
snapshot -i, except two coordinate-based steps: the empty-space long-press that enters edit mode, and the widget-gallery search-result rows, which return unlabeled accessibility nodes. - SpringBoard labels vary by iOS version and locale; discover them from the current snapshot rather than hard-coding strings like
EditorAdd Widget. - Reopen the app bundle under test to return to normal app automation after a SpringBoard step.