ios-agent

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.

Release the device and shut down its WebDriverAgent runner.

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.

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

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.

Search the screen's accessibility tree, including what the digest hides. Prefer `ios_observe` with a `query` when you want a usable digest you can tap from: what it returns carries refs. Use this when `ios_observe` shows nothing matching but the text is on the device, or when a tap keeps missing. It reads the tree before compaction, so it reports matches the digest dropped, which `ios_observe` by construction cannot, and each one says whether it is `shown` or `hidden`. A hidden match is the diagnosis: the words are on screen and perception is why you cannot reach them. Name it by the `id` reported here.

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

Stop this session from taking further action.

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.

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

Bring an app to the foreground and return its screen.

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

List iOS Simulators and attached physical iPhones available for automation. `ready` is false when something blocks automation; `blockers` says what.

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.

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.

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.

Press a hardware button or a keyboard key.

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.

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

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` each element is boxed and labelled with its ref, so you can pick one by eye and pass it to an action tool. Annotating re-reads the screen first, so the refs on the image are the current ones rather than whatever was observed last. That costs a tree fetch, and needs the `vision` extra installed.

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.

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

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

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.

Set a switch, slider, or picker wheel to a value. 'on' or 'off' for a switch, a percentage such as '40%' or a fraction for a slider, and the option spelled the way the wheel spells it for a picker. A wheel is turned a row at a time and read back after each one, so an option it does not contain fails listing what it does. 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. Steppers and segmented controls are not set this way. iOS reports their parts and the digest shows them, so tap 'Increment', 'Decrement', or the segment by its own label.

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

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.

Force-quit an app.

Type into a field, focusing it first when a ref or target is given. The field is read back afterwards. If the text did not land, the call fails with `typed.shown` saying what the field holds; `reformatted` means it landed with the app's own capitalisation or formatting.

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.

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.