Device CLI Reference

Test mobile apps with the same dev device commands in local and Remote SSH sessions.

View as Markdown

Where the device runs#

dev device controls simulators and emulators on the agent's execution host. The connected Agentastic app displays the live viewer beside the agent.

Agent locationDevice locationSupported platforms
Local MacThe same MaciOS simulators and Android emulators
Remote Mac over SSHThe remote MaciOS simulators and Android emulators
Remote Linux over SSHThe Linux serverAndroid emulators
Cloud or container—Managed device viewer unavailable

A Linux agent does not automatically use simulators on your Mac. Run the agent on a Mac for iOS testing. Routing a Linux agent to a separate Mac device host is not implemented. Remote viewers currently require SSH port forwarding and the owning Mac app to remain connected.

The execution host needs Node.js 22 or newer, npm, and the relevant platform tools: Xcode with simulator runtimes, or the Android SDK with an emulator. Agentastic installs its pinned device automation tools on first use; it does not install the platform SDK or create a simulator for you.

Make device-use available to the agent#

Enable the Devices plugin for the run to deliver the bundled device-use skill and, when the agent supports MCP, four tools: device_list, device_open, device_screenshot, and device_close. You can also attach the skill directly and use the CLI without MCP.

Selected skills are copied into local worktrees and uploaded to SSH worktrees. A skill in the app's library is not automatically attached to every agent. Start a new run to receive changes to its plugin or skill selection.

Workflow#

Run these commands in the same terminal or Chat:

bash
dev device --help dev device list dev device open platform=ios id=<id-from-list> # Android: dev device open platform=android id=<id-from-list> dev device apps dev device app-open <bundle-or-package-id> --foreground dev device snapshot -i dev device click '@e3' --settle dev device fill '@e5' 'hello' --settle dev device screenshot /absolute/path/evidence.png dev device close

open boots or attaches to the device, selects it for the calling terminal or Chat, and creates the viewer. It does not launch an app. Its JSON result includes device_id, platform, browser_id, agent_device_command, and agent_device_quick_start. Remote success requires the owning app to confirm the viewer tab.

The viewer belongs to the requesting Chat or terminal's worktree. If you are working elsewhere, it is added to the origin's saved layout and appears when you return there. Opening or closing it does not switch your current worktree. Each viewer stays on its own device, also after its pane is rebuilt, so agents testing in different worktrees never see each other's simulators.

On this Mac, the device_* MCP tools act for the agent that started them, also under agents such as Codex that start MCP servers without their environment. A local caller with no terminal or Chat, such as dev in another terminal app, shares one selection per worktree.

Copy accessibility references exactly, including any ~sN suffix. Inspect the returned UI diff after acting and take a new snapshot when you need new targets.

screenshot writes a PNG on the execution host. On SSH, its path is on the remote server.

When devices shut down#

Run close when testing is done. It removes the viewer and the selection and ends the terminal or Chat's automation session. A simulator or emulator that open booted is shut down once no other agent holds it; its JSON reports "shutdown": true. A device that was already running when it was opened keeps running.

A session ends the same way after an hour with no device commands and no one watching its viewer, so a finished agent that never closes does not leave its device running. The agent's next command explains how to open it again. Set AGENTASTIC_DEVICE_IDLE_MINUTES in the app's or remote daemon's environment to change the hour. Agentastic records what it started on the execution host, so quitting the app or restarting the remote server does not lose track of it.

Agents in one worktree share an automation session per device, so a Chat's next run continues where its last run left off. Agents in different worktrees cannot drive one device at the same time; the second receives DEVICE_IN_USE until the first closes its session or leaves it unused for an hour. open boots a device that has never run, so an agent can create a dedicated simulator with xcrun simctl create, open it, and delete it afterwards.

Commands and output#

CommandPurpose
listReturn devices and discovery errors as JSON
open platform=ios|android id=<id>Select a device and confirm its viewer
appsFind installed app identifiers
app-open <id> --foregroundLaunch an installed app
snapshot -iInspect the accessibility tree
click, fill, type, swipe, scroll, waitInteract with or inspect the selected device
screenshot <path>Save a PNG on the execution host
closeEnd this terminal or Chat's device session and viewer
run <command> [args...]Forward an approved agent-device command
run help <command>Read the underlying command's flags
mcpRun the lifecycle and image MCP server over standard input/output

Use --focus on open to permit keyboard focus changes. Lifecycle commands return JSON. Action commands print their output; dev --json device snapshot -i returns the output envelope. Arguments after run belong to agent-device.

Troubleshooting#

  • No devices: read the listing's errors and check SDKs/runtimes on the execution host.
  • Node.js required: install Node.js 22+ and npm on the execution host.
  • Open a device first: repeat open in this terminal or Chat; another agent's selection does not apply. The error says when the session ended because it went unused for an hour.
  • DEVICE_IN_USE: an agent in another worktree holds the device. Pick another device from list, or wait until that agent closes its session.
  • Viewer could not be confirmed: check the owning app's SSH connection and worktree. A working simulator screenshot does not prove the viewer appeared.
  • Remote dev ping or dev instances fails: those commands belong to the desktop CLI. Use dev --help and dev device list in the remote session.
  • Unknown device command on an older server: reconnect with the updated Agentastic app so it deploys its matching server and managed CLI.