Docs / Operation reference / device operations

device operations#

8 operations. Generated from assets/operations.json; all areas.

device.list#

Find devices

Discover connected Android and iOS devices. Diagnostics distinguish missing tools from no device.

Annotations: read-only, idempotent, open world.

tomaccoctl call device.list

device.info#

Device information

Read Android properties/display settings or iOS device information. For Android, health sums up the device in the same call, read-only: Android version, SDK and security patch, battery level, state, health and temperature, free and total storage on /data, screen size and density in pixels and dp, and uptime in seconds; a part the device does not report is null.

Annotations: read-only, idempotent, open world.

tomaccoctl call device.info '{"platform":"android","device":"<device>"}'

device.label#

Name or pin a device

Give a device a nickname or pin it as a favourite. device.list then shows the nickname as name (the earlier name stays as original_name), marks pinned devices and lists them first; the desktop and the Omarchy panel show the same. An emulator is named by its AVD, so the name stays when its serial changes; a phone by its serial or UDID. An emulator that is off is named with device avd:NAME, its AVD name from android.avds, which also lists nickname and pinned. An empty nickname removes it and pinned false unpins. With neither, the call only reads. The result lists every label.

Annotations: writes, idempotent, closed world.

tomaccoctl call device.label '{"device":"<device>"}'

device.install#

Install app

Install one or split APKs, or one .aab through bundletool (built for the selected device, then installed), or one signed IPA on the selected device.

Annotations: destructive, idempotent, open world.

tomaccoctl call device.install '{"platform":"android","device":"<device>","paths":["<path>"]}'

device.app#

Control app

Launch, stop, uninstall or clear application data. On an iPhone, go-ios launches, stops and uninstalls the installed app bundle_id names (xtool's XTL- prefix may be left out); without go-ios, xtool launches and uninstalls. iOS has no clear-data.

Annotations: destructive, not idempotent, open world.

tomaccoctl call device.app '{"platform":"android","device":"<device>","bundle_id":"<bundle_id>"}'

device.screenshot#

Device screenshot

Capture an actual device display to a file. On an iPhone this uses idevicescreenshot, or go-ios screenshot when idevicescreenshot is not installed; both need the developer image mounted (ios.prepare).

Annotations: writes, not idempotent, open world.

tomaccoctl call device.screenshot '{"platform":"android","device":"<device>","path":"<path>"}'

device.capture#

Device image for agents

Capture the real device display and wait up to 30 seconds. MCP returns the PNG inline, with artifact metadata.

Annotations: writes, not idempotent, open world.

tomaccoctl call device.capture '{"platform":"android","device":"<device>","path":"<path>"}'

device.logs#

Device logs

Capture bounded logcat/syslog output as a job; optionally filter by app or tag. On Android 12 and newer, bundle_id selects the app by its user ID, also across restarts and before launch; older Android needs the app running. On an iPhone, bundle_id follows the app's process, its executable as go-ios apps names it, and the job names it as process; idevicesyslog filters when it is installed, otherwise go-ios syslog runs through Tomacco's filter. filter keeps lines containing that text.

Annotations: writes, not idempotent, open world.

tomaccoctl call device.logs '{"platform":"android","device":"<device>"}'

View this page as Markdown on GitHub