Device CLI Reference
Test mobile apps with the same dev device commands in local and Remote SSH sessions.
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:
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 closeopen 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#
| 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 | End 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 |
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
errorsand 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
openin 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 fromlist, 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 pingordev instancesfails: those commands belong to the desktop CLI. Usedev --helpanddev device listin 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.