Device CLI Reference

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

On this page

Where the device runs
Make device-use available to the agent
Workflow
Commands and output
Troubleshooting

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 location	Device location	Supported platforms
Local Mac	The same Mac	iOS simulators and Android emulators
Remote Mac over SSH	The remote Mac	iOS simulators and Android emulators
Remote Linux over SSH	The Linux server	Android 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.

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. close removes the viewer and selection without powering off the simulator or emulator. dev device run close ends the automation session.

Commands and output#

Command	Purpose
`list`	Return devices and discovery errors as JSON
`open platform=ios\|android id=<id>`	Select a device and confirm its viewer
`apps`	Find installed app identifiers
`app-open <id> --foreground`	Launch an installed app
`snapshot -i`	Inspect the accessibility tree
`click`, `fill`, `type`, `swipe`, `scroll`, `wait`	Interact with or inspect the selected device
`screenshot <path>`	Save a PNG on the execution host
`close`	Close this terminal or Chat's viewer
`run <command> [args...]`	Forward an approved agent-device command
`run help <command>`	Read the underlying command's flags
`mcp`	Run 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.
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.