### Starting MCP Server

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/installation.md

Start the MCP server to expose direct structured tools for installed agent-device commands.

```bash
agent-device mcp
```

--------------------------------

### Web Automation Setup and Basic Commands

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Use these commands to set up the web backend, verify its status, open a URL, take a snapshot, get text, check visibility, find text, click, fill fields, wait for text, dump network traffic, take screenshots, set viewport size, and close the browser session.

```bash
agent-device web setup
```

```bash
agent-device web doctor
```

```bash
agent-device open "https://example.com" --platform web
```

```bash
agent-device snapshot -i --platform web
```

```bash
agent-device get text @e2 --platform web
```

```bash
agent-device is visible 'label="Welcome"' --platform web
```

```bash
agent-device find text "Welcome" exists --platform web
```

```bash
agent-device click @e12 --platform web
```

```bash
agent-device fill @e13 "test@example.com" --platform web
```

```bash
agent-device wait text "Welcome" --platform web
```

```bash
agent-device network dump 25 --include headers --platform web
```

```bash
agent-device screenshot ./artifacts/web-home.png --platform web
```

```bash
agent-device screenshot ./artifacts/web-full.png --platform web --fullscreen
```

```bash
agent-device viewport 1280 900 --platform web
```

```bash
agent-device close --platform web
```

--------------------------------

### Discover, Navigate, Snapshot, and Interact with Apps

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/quick-start.md

Follow these steps to discover installed applications, open a specific app, take a snapshot of the UI to get element references, and interact with those elements. Always re-snapshot after major UI changes or before new interactions.

```bash
# 1. Discover the installed app identifier when needed
agent-device apps --platform ios # or android
```

```bash
# 2. Navigate
agent-device open SampleApp --platform ios # or android
```

```bash
# 3. Snapshot to get element refs
agent-device snapshot -i
# Output:
# @e1 [heading] "Sample App"
# @e2 [button] "Settings"
# [off-screen below] 2 interactive items: "Privacy", "Battery"
```

```bash
# 4. Interact using refs
agent-device click @e2
```

```bash
# 5. Re-snapshot before next interactions; if a target only appears in an off-screen summary, scroll and re-snapshot first
agent-device snapshot -i
```

```bash
# 6. Optional: see structural changes since last baseline
agent-device diff snapshot
# or, from snapshot-focused help/examples:
agent-device snapshot --diff
```

--------------------------------

### Record Start Command Request

Source: https://github.com/callstack/agent-device/blob/main/ios-runner/RUNNER_PROTOCOL.md

Example of a recordStart command request specifying output path, frame rate, and maximum size.

```json
{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30, "maxSize": 720 }
```

--------------------------------

### Global Installation and Version Check

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/installation.md

Install agent-device globally and verify the installation. Use this for standard agent workflows.

```bash
npm install -g agent-device@latest
agent-device --version
agent-device help
```

--------------------------------

### Install and Run SkillGym Smoke Suite

Source: https://github.com/callstack/agent-device/blob/main/test/skillgym/README.md

Install project dependencies and run the default SkillGym smoke suite from the project root.

```bash
cd /absolute/path/to/agent-device
pnpm install
pnpm test:skillgym
```

--------------------------------

### Get App State and Lists

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Retrieve the current application state or lists of installed applications. Use `--all` to include system apps.

```bash
agent-device appstate
agent-device apps --platform ios
agent-device apps --platform ios --all
agent-device apps --platform android
agent-device apps --platform android --all
```

--------------------------------

### Web Automation First-Run Flow

Source: https://github.com/callstack/agent-device/blob/main/docs/agents/web-backend.md

Execute this sequence for initial web automation setup and common tasks. Ensure the managed backend is installed and configured before running.

```sh
agent-device web setup
agent-device open "https://example.com" --platform web
agent-device snapshot -i --platform web
agent-device viewport 1280 900 --platform web
agent-device screenshot ./artifacts/web-full.png --platform web --fullscreen
agent-device network dump 25 --platform web
agent-device close --platform web
```

--------------------------------

### Install and Run Test App (iOS)

Source: https://github.com/callstack/agent-device/blob/main/examples/test-app/README.md

Install dependencies and run the Agent Device Tester app on iOS. This is the first step before testing with agent-device.

```bash
pnpm test-app:install
pnpm test-app:ios
```

--------------------------------

### Install Source

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Utilities for managing and validating install sources.

```APIDOC
## Install Source

### Description
Functions for handling application installation sources.

### Constants
- `ARCHIVE_EXTENSIONS`

### Functions
- `isBlockedIpAddress(address)`: Checks if an IP address is blocked.
- `isBlockedSourceHostname(hostname)`: Checks if a hostname is blocked.
- `isTrustedInstallSourceUrl(sourceUrl)`: Checks if an install source URL is trusted.
- `materializeInstallablePath(options)`: Materializes an installable path.
- `validateDownloadSourceUrl(url)`: Validates a download source URL.

### Types
- `MaterializeInstallSource`
- `MaterializedInstallable`
```

--------------------------------

### Install and Run Test App (Android)

Source: https://github.com/callstack/agent-device/blob/main/examples/test-app/README.md

Install dependencies and run the Agent Device Tester app on Android. This is the first step before testing with agent-device.

```bash
pnpm test-app:install
pnpm test-app:android
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/callstack/agent-device/blob/main/CONTRIBUTING.md

Run this command to install all necessary project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Install and Check Agent Device CLI Version

Source: https://github.com/callstack/agent-device/blob/main/README.md

Installs the agent-device CLI globally and verifies the installation by checking the version and displaying help for workflows.

```bash
npm install -g agent-device@latest
agent-device --version
agent-device help workflow
```

--------------------------------

### Example Snapshot Output

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/snapshots.md

This example shows the output of the `agent-device snapshot -i` command, including visible and off-screen interactive items.

```bash
agent-device snapshot -i
# Output:
# Snapshot: 9 visible nodes (14 total)
# @e1 [application] "Contacts"
#   @e2 [window]
#     @e3 [other]
#   @e4 [other] "Lists"
#     @e5 [navigation-bar] "Lists"
#       @e6 [button] "Lists"
#       @e7 [text] "Contacts"
#     @e8 [other] "John Doe"
#       @e9 [other] "John Doe"
# [off-screen below] 2 interactive items: "All Contacts", "New List"
```

--------------------------------

### Open an Application

Source: https://github.com/callstack/agent-device/blob/main/README.md

Starts a new session by opening the specified application on the target platform.

```bash
# Start a session.
agent-device open SampleApp --platform ios
```

--------------------------------

### Agent Device Help Commands

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/agent-setup.md

Use these commands to get help on agent-device workflows and dogfooding capabilities. The installed CLI remains authoritative for exact command syntax.

```bash
agent-device help
```

```bash
agent-device help workflow
```

```bash
agent-device help dogfood
```

--------------------------------

### Install App from Source URL

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Installs an application from a URL or a GitHub Actions artifact. This command is used when the artifact is already available at a remote location accessible by the daemon.

```bash
agent-device install-from-source https://example.com/builds/app.apk --platform android
```

```bash
agent-device install-from-source https://example.com/builds/app.aab --platform android
```

```bash
agent-device install-from-source --github-actions-artifact thymikee/RNCLI83:6635342232 --platform android
```

--------------------------------

### Install and Run Test App from App Folder (iOS)

Source: https://github.com/callstack/agent-device/blob/main/examples/test-app/README.md

Navigate into the test-app directory, install dependencies ignoring workspace, and run the app on iOS. This is an alternative to running from the repo root.

```bash
cd examples/test-app
pnpm install --ignore-workspace
pnpm ios
```

--------------------------------

### Manage App Installations

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/quick-start.md

Install, reinstall, or install from source for Android and iOS applications. Supports various binary formats and remote URLs. Ensure necessary tools like bundletool are in PATH for .aab installations.

```bash
agent-device screenshot page.png         # Save to specific path
agent-device install com.example.app ./build/app.apk     # Install app binary in-place
agent-device install-from-source https://example.com/builds/app.apk --platform android
agent-device reinstall com.example.app ./build/app.apk   # Fresh-state uninstall + install
```

--------------------------------

### Install and Open Android App from URL

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Installs an Android application from a URL and then opens it. The response provides identity details for relaunching the app. Cleans up materialization resources if applicable.

```typescript
const androidClient = createAgentDeviceClient({ session: 'qa-android' });

const installed = await androidClient.apps.installFromSource({
  platform: 'android',
  retainPaths: true,
  retentionMs: 60_000,
  source: { kind: 'url', url: 'https://example.com/app.apk' },
});

await androidClient.apps.open({
  platform: 'android',
  app: installed.launchTarget,
});

console.log(installed.packageName, installed.launchTarget);

if (installed.materializationId) {
  await androidClient.materializations.release({
    materializationId: installed.materializationId,
  });
}

await androidClient.sessions.close();
```

--------------------------------

### Start Remote Proxy on Host Machine

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/remote-proxy.md

Run this command on the Mac with simulator or device access to start the proxy. It will output a daemon base URL and an authentication token.

```bash
agent-device proxy --port 4310
```

--------------------------------

### Install and Run Test App from App Folder (Android)

Source: https://github.com/callstack/agent-device/blob/main/examples/test-app/README.md

Navigate into the test-app directory, install dependencies ignoring workspace, and run the app on Android. This is an alternative to running from the repo root.

```bash
cd examples/test-app
pnpm install --ignore-workspace
pnpm android
```

--------------------------------

### Canonical Recipe: Open App, Choose Option, Verify

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/batching.md

An example sequence of batch commands to open an app, wait for a home screen, open an action menu, select an option, and verify its successful execution.

```json
[
  { "command": "open", "input": { "app": "com.example.app", "platform": "android" } },
  { "command": "wait", "input": { "kind": "text", "text": "Home", "timeoutMs": 3000 } },
  {
    "command": "press",
    "input": { "target": { "kind": "selector", "selector": "label=\"More actions\" role=button" } }
  },
  { "command": "wait", "input": { "kind": "text", "text": "Scan document", "timeoutMs": 2000 } },
  { "command": "press", "input": { "target": { "kind": "selector", "selector": "label=\"Scan document\"" } } },
  { "command": "wait", "input": { "kind": "text", "text": "Document uploaded", "timeoutMs": 15000 } },
  { "command": "is", "input": { "predicate": "visible", "selector": "label=\"Document uploaded\"" } }
]
```

--------------------------------

### Install agent-device Skill

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/agent-setup.md

Use this command to install the agent-device skill when your agent runtime supports skills. This skill acts as a router for skill-aware clients.

```bash
npx skills add callstack/agent-device
```

--------------------------------

### Execute agent-device Commands after CLAUDE.md Setup

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/agent-setup.md

Run essential agent-device commands after configuring CLAUDE.md to verify setup and access help documentation.

```bash
agent-device --version
agent-device help workflow
agent-device help dogfood
agent-device help react-native
```

--------------------------------

### Install and Run Android Snapshot Helper

Source: https://github.com/callstack/agent-device/blob/main/android-snapshot-helper/README.md

Installs the Android Snapshot Helper APK onto a device and runs the instrumentation. The `-t` flag is required for test-only APKs. Adjust parameters like `waitForIdleTimeoutMs` and `maxDepth` as needed.

```sh
VERSION="$(node -p 'require("./package.json").version')"
adb install -r -t ".tmp/android-snapshot-helper/agent-device-android-snapshot-helper-$VERSION.apk"
adb shell am instrument -w \
  -e waitForIdleTimeoutMs 500 \
  -e waitForIdleQuietMs 100 \
  -e timeoutMs 8000 \
  -e maxDepth 128 \
  -e maxNodes 5000 \
  com.callstack.agentdevice.snapshothelper/.SnapshotInstrumentation
```

--------------------------------

### Install iOS App In-Place

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Install an iOS application from a local .app or .ipa file without uninstalling the existing version. This supports simulators and physical devices.

```bash
agent-device install com.example.app ./build/MyApp.app --platform ios
```

--------------------------------

### Install Expo Test App Dependencies

Source: https://github.com/callstack/agent-device/blob/main/CONTRIBUTING.md

Installs the necessary dependencies for the Expo test application located in the examples/test-app directory.

```bash
pnpm test-app:install
```

--------------------------------

### Start Expo Test App

Source: https://github.com/callstack/agent-device/blob/main/CONTRIBUTING.md

Starts the Expo test application, preparing it for testing or debugging.

```bash
pnpm test-app:start
```

--------------------------------

### Example Default Snapshot Output

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

This is an example of the output format for memory snapshots when not dumping large artifacts directly. It includes the artifact type, path, and size.

```text
Memory artifact (android-hprof): /tmp/app.hprof (42MB)
```

--------------------------------

### Install Android App In-Place

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Install an Android application from a local APK or AAB file without uninstalling the existing version. This is useful for upgrade scenarios.

```bash
agent-device install com.example.app ./build/app.apk --platform android
```

--------------------------------

### Canonical Recipe: Open App, Type, Send

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/batching.md

An example sequence of batch commands to open a specific app, wait for an inbox, select a contact, type a message, and send it.

```json
[
  { "command": "open", "input": { "app": "com.example.chat", "platform": "android" } },
  { "command": "wait", "input": { "kind": "text", "text": "Inbox", "timeoutMs": 3000 } },
  { "command": "press", "input": { "target": { "kind": "selector", "selector": "label=\"Inbox\" role=button" } } },
  { "command": "press", "input": { "target": { "kind": "selector", "selector": "label=\"Morgan Lee\"" } } },
  {
    "command": "fill",
    "input": {
      "target": { "kind": "selector", "selector": "label=\"Message\" role=text-field" },
      "text": "sent the update"
    }
  },
  { "command": "press", "input": { "target": { "kind": "selector", "selector": "label=\"Send\" role=button" } } },
  { "command": "wait", "input": { "kind": "text", "text": "sent the update", "timeoutMs": 3000 } }
]
```

--------------------------------

### Agent Device Help Workflow

Source: https://github.com/callstack/agent-device/blob/main/skills/agent-device/SKILL.md

Access the help documentation for agent-device workflows. This guide provides exact command shapes, platform limits, and current workflow guidance.

```bash
agent-device help workflow
```

--------------------------------

### Example Perfetto Stop Output

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

This example shows the compact agent evidence returned after a successful Perfetto trace stop, including state, output path, size, and method. The raw trace file remains on disk.

```text
state: "stopped"
outPath: "/tmp/app.perfetto-trace"
sizeBytes: 5392410
method: "adb-shell-perfetto"
```

--------------------------------

### client.recording.record

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Starts a recording session on the device.

```APIDOC
## client.recording.record

### Description
Starts a recording session on the device.

### Method
POST

### Endpoint
/recording/record

### Parameters
#### Query Parameters
- **action** (string) - Required - The action to perform ('start').
- **path** (string) - Required - The path to save the recording.
- **maxSize** (number) - Optional - The maximum size of the recording in pixels (longest edge).
- **quality** (string) - Optional - The output quality of the recording ('low', 'medium', 'high').

### Request Example
{
  "example": "{\"action\": \"start\", \"path\": \"/sdcard/recording.mp4\", \"maxSize\": 1080, \"quality\": \"medium\"}"
}

### Response
#### Success Response (200)
- **result** (object) - Daemon-shaped object with typed known fields.

#### Response Example
{
  "example": "{\"result\": {}}"
}
```

--------------------------------

### Global Install Configuration for MCP Server

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/agent-setup.md

Use this JSON configuration to set up the agent-device MCP server globally. This ensures direct structured tools are exposed for installed CLI commands.

```json
{
  "mcpServers": {
    "agent-device": {
      "command": "agent-device",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Get Agent Device Text or Attributes

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Retrieve specific information from an agent device. Use 'get text' to fetch textual representation and 'get attrs' to retrieve attributes of a specified element.

```bash
agent-device get text @e1
```

```bash
agent-device get attrs @e1
```

--------------------------------

### Android installFromSource()

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Installs an application from a given source URL on an Android device. It returns app identity details necessary for relaunching the application and allows for optional path retention and cleanup.

```APIDOC
## Android `installFromSource()`

```ts
const androidClient = createAgentDeviceClient({ session: 'qa-android' });

const installed = await androidClient.apps.installFromSource({
  platform: 'android',
  retainPaths: true,
  retentionMs: 60_000,
  source: { kind: 'url', url: 'https://example.com/app.apk' },
});

await androidClient.apps.open({
  platform: 'android',
  app: installed.launchTarget,
});

console.log(installed.packageName, installed.launchTarget);

if (installed.materializationId) {
  await androidClient.materializations.release({
    materializationId: installed.materializationId,
  });
}

await androidClient.sessions.close();
```

On Android, a successful `installFromSource()` response returns enough app identity to relaunch the installed app:

- `packageName`
- `launchTarget`

If the daemon cannot determine installed app identity, the request fails instead of returning an empty success payload.
```

--------------------------------

### Agent Device Help Commands

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Run these commands to get help on specific agent workflow topics. This is useful for understanding the available commands and their usage.

```bash
agent-device help
```

```bash
agent-device help workflow
```

```bash
agent-device help debugging
```

```bash
agent-device help react-native
```

```bash
agent-device help react-devtools
```

```bash
agent-device help remote
```

```bash
agent-device help web
```

```bash
agent-device help macos
```

```bash
agent-device help dogfood
```

--------------------------------

### Create agent-device Project Rule (CLI)

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/agent-setup.md

Use this bash command to create a project rule file for agent-device. This setup ensures auditable commands and terminal visibility.

```bash
mkdir -p .cursor/rules
cat > .cursor/rules/agent-device.mdc <<'EOF'
---
description: Use agent-device for app and device automation
alwaysApply: true
---

Use agent-device only for app/device automation tasks.
Before planning device work, run `agent-device --version` and read `agent-device help workflow`.
For exploratory QA, read `agent-device help dogfood`.
For logs, network, traces, or runtime failures, read `agent-device help debugging`.
For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`.
For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.

Use the CLI in Cursor's integrated terminal.
If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the absolute binary path instead of using `npx -y agent-device@latest`.
Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`.
Keep mutating commands against one session serial.
EOF
```

--------------------------------

### Install App from GitHub Actions Artifact

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Installs an application from a GitHub Actions artifact. This method is suitable for CI/CD environments and requires specifying the platform, owner, repository, and artifact ID.

```typescript
await client.apps.installFromSource({
  platform: 'android',
  source: {
    kind: 'github-actions-artifact',
    owner: 'acme',
    repo: 'mobile',
    artifactId: 1234567890,
  },
});
```

--------------------------------

### Example Memory Sample JSON Shape

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

This is an example of the JSON structure returned by the `perf memory sample` command, focusing on memory metrics and top consumers.

```json
{"metrics":{"memory":{"available":true,"totalPssKb":562958,"totalRssKb":570304,"topConsumers":[{"name":"Dalvik Heap","pssKb":213456}]}}}
```

--------------------------------

### Install and Enable ADB Keyboard IME

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/known-limitations.md

Install and enable a custom ADB keyboard IME for Android to work around issues with non-ASCII text input via `adb shell input text`.

```bash
adb -s <serial> install <path-to-adbkeyboard.apk>
```

```bash
adb -s <serial> shell ime enable com.android.adbkeyboard/.AdbIME
```

```bash
adb -s <serial> shell ime set com.android.adbkeyboard/.AdbIME
```

--------------------------------

### Snapshot Command Request

Source: https://github.com/callstack/agent-device/blob/main/ios-runner/RUNNER_PROTOCOL.md

Example of a snapshot command request with options for interactivity, depth, scope, and raw output.

```json
{
  "command": "snapshot",
  "interactiveOnly": true,
  "depth": 2,
  "scope": "app",
  "raw": false
}
```

--------------------------------

### Start and Stop Tracing

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Use these commands to begin and end trace-log capture for the active session. A path can be optionally provided to specify the trace artifact location.

```bash
agent-device trace start
agent-device trace start session.trace
agent-device trace stop
agent-device trace stop session.trace
```

--------------------------------

### Remote Configuration JSON

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Example JSON configuration for establishing a remote connection to the agent device. This file specifies connection details and session parameters.

```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"
}
```

--------------------------------

### React Native DevTools Profiling Start and Stop

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Initiate and terminate profiling sessions for React Native components. Use these commands to capture performance data during specific intervals.

```bash
agent-device react-devtools profile start
agent-device react-devtools profile stop
```

--------------------------------

### Prepare iOS Runner for CI

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Use this command to set up an Apple runner in a CI environment before running snapshot, replay, or test commands. It ensures the runner is built or reused, started, and verified for health checks.

```bash
agent-device prepare ios-runner --platform ios --timeout 240000
```

--------------------------------

### Run Android MultiTouch Helper

Source: https://github.com/callstack/agent-device/blob/main/android-multitouch-helper/README.md

Installs the helper APK and runs an instrumentation test with a base64 encoded JSON payload for gesture injection.

```sh
PAYLOAD="$(printf '%s' '{"kind":"transform","x":672,"y":1500,"dx":80,"dy":-40,"scale":1.8,"degrees":35,"durationMs":700}' | base64)"
関連記事 install -r -t ".tmp/android-multitouch-helper/agent-device-android-multitouch-helper-$VERSION.apk"
関連記事 shell am instrument -w \
  -e payloadBase64 "$PAYLOAD" \
  com.callstack.agentdevice.multitouchhelper/.MultiTouchInstrumentation
```

--------------------------------

### Start and Stop Recordings

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Control screen recording using client.recording.record. Specify action, path, max size, and quality for recording parameters.

```typescript
client.recording.record({ action: 'start', path, maxSize: 1024, quality: 'medium' })
```

--------------------------------

### client.devices.boot

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Boots the device.

```APIDOC
## client.devices.boot

### Description
Boots the device.

### Method
POST

### Endpoint
/devices/boot

### Parameters
No parameters required.

### Request Example
{
  "example": "{}"
}

### Response
#### Success Response (200)
- **result** (object) - Daemon-shaped object with typed known fields.

#### Response Example
{
  "example": "{\"result\": {}}"
}
```

--------------------------------

### Recommended Agent Rule Configuration

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/agent-setup.md

This rule should be added as a project rule, custom instruction, or skill equivalent. It guides the agent on using agent-device for automation, including specific commands for version checks, help, and debugging. It also provides guidance on handling PATH issues and preferring structured MCP tools over generic shell execution.

```text
Use agent-device only for app/device automation tasks. Before planning commands, run `agent-device --version` and read `agent-device help workflow`. For exploratory QA, read `agent-device help dogfood`. For logs, network, traces, or runtime failures, read `agent-device help debugging`. For React Native component trees, props/state/hooks, slow renders, or rerenders, read `agent-device help react-devtools`. For React Native apps, overlays, Metro/Fast Refresh blockers, and routing to React DevTools or debugging evidence, read `agent-device help react-native`.

Use MCP tools or the CLI in the integrated terminal. If `agent-device` is not on PATH but the user installed it globally in another shell, resolve the command the same way the user would from a normal terminal session and run that absolute path instead. This may require inspecting shell startup behavior or package-manager/global bin locations; do not assume the agent process `PATH` is the user's `PATH`. Do not silently fall back to `npx -y agent-device@latest`; ask or use an exact version. MCP exposes structured tools backed by the agent-device client; it does not expose generic shell execution. Prefer `open -> snapshot -i -> act -> re-snapshot -> verify -> close`. Use current refs such as `@e3` for exploration and selectors for durable replay. Keep mutating commands against one session serial. Capture screenshots, logs, network, perf, traces, recordings, and `.ad` replay scripts only when they add evidence.
```

--------------------------------

### Get Session State Directory

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Retrieves the resolved daemon state directory without starting or contacting the daemon. This mirrors the `session state-dir` CLI command.

```typescript
client.sessions.stateDir()
```

--------------------------------

### Client Initialization and Basic Operations

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Demonstrates how to create an Agent Device client and perform common operations like listing devices and apps, opening applications, capturing snapshots, and closing sessions.

```APIDOC
## Client Initialization

### Description
Initializes the Agent Device client with session and lock configurations.

### Method
`createAgentDeviceClient`

### Parameters
- **session** (string) - Required - The session identifier.
- **lockPolicy** (string) - Required - The policy for locking.
- **lockPlatform** (string) - Required - The platform to lock.

## List Devices

### Description
Retrieves a list of available devices for a specified platform.

### Method
`client.devices.list`

### Parameters
- **platform** (string) - Required - The target platform (e.g., 'ios', 'web').

### Response
#### Success Response (200)
- **devices** (array) - A list of device objects.
  - **id** (string) - The unique identifier of the device.
  - **name** (string) - The name of the device.

## List Applications

### Description
Retrieves a list of available applications for a specified platform.

### Method
`client.apps.list`

### Parameters
- **platform** (string) - Required - The target platform (e.g., 'ios', 'web').

## Open Application

### Description
Opens a specified application on a device. Supports capturing launch console output and using Xcode Device Hub.

### Method
`client.apps.open`

### Parameters
- **app** (string) - Optional - The application identifier (e.g., bundle ID).
- **platform** (string) - Required - The target platform (e.g., 'ios', 'web').
- **udid** (string) - Optional - The unique device identifier.
- **runtime** (object) - Optional - Runtime configuration for the application.
  - **metroHost** (string) - The Metro host.
  - **metroPort** (number) - The Metro port.
- **launchConsole** (string) - Optional - Path to a file to capture launch console output.
- **deviceHub** (boolean) - Optional - If true, uses Xcode Device Hub.
- **url** (string) - Optional - URL to open for web platform.

## Capture Snapshot

### Description
Captures a snapshot of the current screen.

### Method
`client.capture.snapshot`

### Parameters
- **interactiveOnly** (boolean) - Optional - Capture only if interactive.
- **platform** (string) - Optional - The target platform (e.g., 'ios', 'web').

## Close Session

### Description
Closes the current client session.

### Method
`client.sessions.close`

## Get Session State Directory

### Description
Retrieves the resolved daemon state directory without starting or contacting the daemon.

### Method
`client.sessions.stateDir`

### Parameters
- **stateDir** (string) - Optional - Explicit override for the state directory.

### Response
#### Success Response (200)
- **stateDir** (string) - The resolved state directory path.
```

--------------------------------

### List and Get Android App State with ADB

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Use these functions when an ADB provider is available. They allow listing all installed applications or retrieving the state of the foreground application.

```typescript
import {
  getAndroidAppStateWithAdb,
  listAndroidAppsWithAdb,
} from 'agent-device/android-adb';

const provider = {
  exec: async (args, options) => await runAdbThroughRemoteTunnel(args, options),
};

const apps = await listAndroidAppsWithAdb(provider.exec); // user-installed apps by default
const foreground = await getAndroidAppStateWithAdb(provider.exec);
```

--------------------------------

### Run Maestro Suite via Expo Go (iOS)

Source: https://github.com/callstack/agent-device/blob/main/examples/test-app/README.md

Start the Expo Go app first and then run the Maestro suite on iOS, passing the Expo Go shell as the target. This is for testing when using Expo Go instead of a standalone build.

```bash
pnpm test-app:maestro:ios -- --open "Expo Go"
```

--------------------------------

### Agent Device Screen Recording Commands

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Start and stop screen recordings. Options include specifying output filenames, frame rates, downscaling, and quality.

```bash
agent-device record start               # Start screen recording to auto filename
agent-device record start session.mp4   # Start recording to explicit path
agent-device record start session.mp4 --fps 30  # Override iOS device runner FPS
agent-device record start session.mp4 --max-size 1024 # Downscale longest edge
agent-device record start session.mp4 --quality high # Higher-quality export (slower)
agent-device record stop                # Stop active recording
```

--------------------------------

### Trace with xctrace (Apple)

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Start and stop trace captures using the xctrace kind for Apple platforms, useful for diagnosing issues like Animation Hitches.

```bash
agent-device perf trace start --kind xctrace --template "Animation Hitches" --out hitches.trace
agent-device perf trace stop --kind xctrace --out hitches.trace
```

--------------------------------

### Reinstall App (Fresh State)

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Uninstalls and installs an application in a single command. Useful for resetting app states in tests. Supports Android and iOS platforms with various binary formats.

```bash
agent-device reinstall com.example.app ./build/app.apk --platform android
```

```bash
agent-device reinstall com.example.app ./build/MyApp.app --platform ios
```

--------------------------------

### List Apps on Android TV

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Retrieves a list of launchable applications on an Android TV target. This helps in verifying installed applications or preparing for further interactions.

```bash
agent-device apps --platform android --target tv
```

--------------------------------

### Handle System Alerts

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

The 'alert' command is used to inspect and interact with system-level alerts on various platforms. It can be used to get alert information, wait for an alert to appear, accept it, or dismiss it. For Android, alert handling is snapshot-derived, and specific UI elements might require direct interaction if not recognized as native alerts.

```bash
agent-device alert
```

```bash
agent-device alert get
```

```bash
agent-device alert wait 3000
```

```bash
agent-device alert accept
```

```bash
agent-device alert dismiss
```

--------------------------------

### Basic agent-device Workflow Commands

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/introduction.md

Demonstrates a typical sequence of commands an agent might use to interact with an application on a device. This includes listing available apps, opening an app, taking a UI snapshot, performing an action, comparing snapshots, and closing the app.

```bash
agent-device apps --platform ios
agent-device open <app-or-url> --platform ios
agent-device snapshot -i
agent-device press @e12
agent-device diff snapshot -i
agent-device close
```

--------------------------------

### Create Agent Device Client and List Devices/Apps

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/client-api.md

Initializes the client with session and lock policies, then lists available iOS devices and applications. Ensure the client is configured with appropriate session and lock settings.

```typescript
import { createAgentDeviceClient } from 'agent-device';

const client = createAgentDeviceClient({
  session: 'qa-ios',
  lockPolicy: 'reject',
  lockPlatform: 'ios',
});

const devices = await client.devices.list({ platform: 'ios' });
const apps = await client.apps.list({ platform: 'ios' });
```

--------------------------------

### Fast Path Reproducer Commands

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/debugging-profiling.md

Use these commands to quickly set up a clean reproduction environment for an application. This includes opening the app, clearing logs, marking specific points, simulating user interactions, capturing network traffic, and collecting performance metrics.

```bash
agent-device open MyApp --platform ios
agent-device logs clear --restart
agent-device logs mark "before repro"
agent-device press 'id="submit"'
agent-device network dump 25 --include headers
agent-device perf metrics --json
agent-device logs path
```

--------------------------------

### Explain SkillGym Artifacts

Source: https://github.com/callstack/agent-device/blob/main/test/skillgym/README.md

After a failed run with explanation questions, use the 'skillgym explain' command with the artifact directory to resume the runner and collect explanations.

```bash
pnpm exec skillgym explain <artifact-dir>
```

--------------------------------

### GitHub Actions Artifact Install Source Configuration

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/configuration.md

Configure agent-device to install from a GitHub Actions artifact. This requires a compatible remote daemon to resolve CI artifacts server-side.

```json
{
  "platform": "android",
  "installSource": {
    "type": "github-actions-artifact",
    "repo": "thymikee/RNCLI83",
    "artifact": "rn-android-emulator-debug-pr-19"
  }
}
```

--------------------------------

### Build and Run SkillGym Directly

Source: https://github.com/callstack/agent-device/blob/main/test/skillgym/README.md

Build the project and then use the SkillGym CLI to run a specific workflow, specifying the suite, config, and case.

```bash
pnpm build
pnpm exec skillgym run \
  ./test/skillgym/suites/agent-device-smoke-suite.ts \
  --config ./test/skillgym/skillgym.config.ts \
  --case open-and-snapshot
```

--------------------------------

### Open Settings and Save Script

Source: https://github.com/callstack/agent-device/blob/main/website/docs/docs/commands.md

Opens device settings and optionally saves the replay script. Specify the platform and session for context.

```bash
agent-device open Settings --platform ios --session e2e --save-script [path]
```