---
title: Device CLI Reference
description: "Test mobile apps with the same dev device commands in local and Remote SSH sessions."
updated: "2026-11-02"
---

## 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.
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 `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.
