From ccd208ea6fac1edeb4bae6e543e423f69e3ea375 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Tue, 10 Mar 2026 12:27:50 +0100 Subject: [PATCH] docs: add missing command reference entries --- website/docs/docs/commands.md | 94 +++++++++++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 3 deletions(-) diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index b7fef150..f42729c5 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -59,6 +59,20 @@ agent-device devices --platform android --android-device-allowlist emulator-5554 - Android: `AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST` (compat: `ANDROID_DEVICE_ALLOWLIST`) - CLI scope flags override environment values. +## Device discovery + +```bash +agent-device devices +agent-device devices --platform ios +agent-device devices --platform android +agent-device devices --platform ios --ios-simulator-device-set /tmp/tenant-a/simulators +agent-device devices --platform android --android-device-allowlist emulator-5554,device-1234 +``` + +- `devices` lists available targets after applying any platform selector or isolation scope flags. +- Use `--platform` to narrow discovery to iOS/tvOS or Android targets. +- Use `--ios-simulator-device-set` and `--android-device-allowlist` when you need tenant- or lab-scoped discovery. + ## Simulator provisioning ```bash @@ -102,6 +116,27 @@ agent-device get attrs @e1 - iOS snapshots use XCTest on simulators and physical devices. - `diff snapshot` compares the current snapshot with the previous session baseline and then updates baseline. +## Wait and alerts + +```bash +agent-device wait 1500 +agent-device wait text "Welcome back" +agent-device wait @e12 +agent-device wait 'role="button" label="Continue"' 5000 +agent-device alert +agent-device alert get +agent-device alert wait 3000 +agent-device alert accept +agent-device alert dismiss +``` + +- `wait` accepts a millisecond duration, `text `, a snapshot ref (`@eN`), or a selector. +- `wait [timeoutMs]` and `wait @ref [timeoutMs]` poll until the target appears or the timeout expires. +- `wait` shares the selector/snapshot resolution flow used by `click`, `fill`, `get`, and `is`. +- `alert` inspects or handles system alerts on iOS simulator targets. +- `alert` without an action is equivalent to `alert get`. +- `alert wait [timeout]` waits for an alert to appear before returning it. + ## Interactions ```bash @@ -139,6 +174,22 @@ agent-device find label "Email" fill "user@example.com" agent-device find role button click ``` +## Assertions + +```bash +agent-device is visible @e3 +agent-device is exists 'role="button" label="Continue"' +agent-device is hidden 'text="Loading..."' +agent-device is editable 'id="email"' +agent-device is selected 'label="Wi-Fi"' +agent-device is text 'id="greeting"' "Welcome back" +``` + +- `is` evaluates UI predicates against a snapshot ref or selector and exits non-zero on failure. +- Supported predicates are `visible`, `hidden`, `exists`, `editable`, `selected`, and `text`. +- `is text ` compares the resolved element text against the expected value. +- `is` accepts the same selector-oriented snapshot flags as `click`, `fill`, `get`, and `wait`. + ## Replay ```bash @@ -161,9 +212,9 @@ agent-device batch --steps '[{"command":"open","positionals":["settings"]}]' ``` - `batch` runs a JSON array of steps in a single daemon request. -- each step has `command`, optional `positionals`, and optional `flags`. -- stop-on-first-error is the supported behavior (`--on-error stop`). -- use `--max-steps ` to tighten per-request safety limits. +- Each step has `command`, optional `positionals`, and optional `flags`. +- Stop-on-first-error is the supported behavior (`--on-error stop`). +- Use `--max-steps ` to tighten per-request safety limits. See [Batching](/docs/batching) for payload format, response shape, and usage guidelines. @@ -388,6 +439,43 @@ tail -50 ~/.agent-device/sessions/default/app.log - Physical-device capture defaults to uncapped (max available) FPS. - `--fps ` (1-120) applies to physical iOS device recording as an explicit FPS cap. +## Tracing + +```bash +agent-device trace start +agent-device trace start session.trace +agent-device trace stop +agent-device trace stop session.trace +``` + +- `trace start [path]` begins trace-log capture for the active session. +- `trace stop [path]` stops capture and optionally writes or finalizes the trace artifact at the provided path. +- `trace` is intended for lower-level session diagnostics than `record` or `logs`. + +## Runtime hints + +```bash +agent-device runtime show +agent-device runtime set --session my-session --platform android --metro-host 10.0.0.10 --metro-port 8081 +agent-device runtime set --session my-session --platform ios --bundle-url "http://10.0.0.10:8081/index.bundle?platform=ios" +agent-device runtime clear +``` + +- `runtime show` prints the current session-scoped runtime hints. +- `runtime set` updates supported hints: `--metro-host`, `--metro-port`, `--bundle-url`, and `--launch-url`. +- `runtime clear` removes previously configured hints for the active session. +- These hints are mainly for React Native and remote/native daemon launch flows. + +## Session inspection + +```bash +agent-device session list +agent-device session list --json +``` + +- `session list` shows active daemon sessions and their tracked device/app context. +- Use `--json` when you want to inspect or script against the raw session metadata. + ## iOS device prerequisites - Xcode + `xcrun devicectl` available.