Check that this machine can drive an iOS device, and say how to fix what it can't.

Run this first when a session fails to start, when a device does not appear, or after an Xcode or iOS upgrade. Every failing check comes with a concrete remedy.

List iOS Simulators and attached physical iPhones available for automation.

ready is false when something blocks automation; blockers says what.

Attach to a device and start driving it.

Boots the simulator or verifies the phone, starts WebDriverAgent, and opens a tuned session. Omitting device prefers an already-booted simulator over a connected iPhone, so acting on a real device is always a deliberate choice.

Report the current session: device, foreground app, and safety state.

Release the device and shut down its WebDriverAgent runner.

List apps installed on the device, with their bundle identifiers.

Bring an app to the foreground and return its screen.

Force-quit an app.

Open a URL or deep link.

Usually the cheapest way to reach a screen: a deep link skips the navigation an agent would otherwise have to tap through.

Install an app from a local .app or .ipa.

Read the screen as a compact list of elements with short refs.

Each line is one element: e7 button "Send" @(340,70). Pass those refs to the action tools rather than coordinates.

If the result says elements were omitted, narrow with query or region instead of raising budget; a smaller answer is usually the more useful one.

Capture the screen as an image.

Use this when an element has no accessibility label, when the layout matters, or when ios_observe cannot find something you can plainly see. With annotate_refs the boxes are labelled with the refs from the last observation, so you can pick one by eye.

Read the text of the screen, or of one element and everything inside it.

Use this to extract content, rather than ios_observe, which is shaped for deciding what to tap.

Wait for something to appear or disappear.

Prefer this over guessing a sleep. It returns as soon as the condition holds, and reports failure rather than raising, so a timeout is something you can reason about.

Read recent device logs. Useful when an app misbehaves and the UI does not say why.

Return the ordered record of everything this session has done.

Useful for explaining what happened, and for turning a successful run into a regression test.

Tap an element and return the resulting screen.

Prefer ref over target; it is exact and cannot be misread. Taps on things like Send, Pay, or Delete need approval first.

Type into a field, focusing it first when a ref or target is given.

Type a stored secret without ever seeing its value.

The value is read from the host keychain and sent straight to the device. Use this for every password and one-time code; never put a real credential into ios_type, where it would enter the transcript.

Set a switch, slider, stepper, or picker to a value.

Prefer this over tapping a switch: it checks the current state first, so asking for 'on' when it is already on does nothing rather than turning it off.

Scroll, optionally until some text comes into view.

With until, this stops as soon as the text appears and gives up when the content stops moving, so it will not spin at the end of a list.

Swipe once, for carousels, page views, and swipe-to-reveal rows.

Drag one element onto another, for reordering lists and moving items.

Press a hardware button or a keyboard key.

Answer a system alert.

Read the alert text before choosing. Accepting blindly is how an agent grants a permission or confirms a deletion nobody wanted.

Stop this session from taking further action.

Clear a halt after a human has decided it is safe to continue.

Set a privacy permission without going through the alert.

Simulator only. On a real phone there is no API for this: drive the Settings app, or answer the permission alert with ios_handle_alert.

Read or write the device clipboard.

Writing is often faster and more reliable than typing a long string, which the on-screen keyboard can mangle with autocorrect.

Change device-level state. Appearance, location, and status bar are Simulator only.