Docs Operations
Operation reference#
Every tomaccoctl operation, 250 in all, generated from assets/operations.json, the schema tomaccoctl schema prints and the MCP server offers as tools. Over MCP the operation name is the tool name.
On this page (29)
Each entry gives the arguments with their types, limits and defaults, what the operation changes (from its MCP annotations) and an example call made from the schema, the same one tomaccoctl help OPERATION prints. Values in angle brackets are placeholders. The agent guide explains jobs, errors and the workflows that combine these.
The annotations are the hints MCP clients see. Read-only changes nothing. Writes changes state but is not marked as deleting data. Destructive may delete or overwrite data: ask the user first. Idempotent means repeating the call with the same arguments has no further effect. Open world means it reaches beyond Tomacco's own state: devices, tools, files or the network.
Error codes lists all 483 error codes with what each means and what to do.
general#
| Operation | Title | Annotation |
|---|---|---|
doctor | Check toolchain | read-only |
capabilities | What this computer can do | read-only |
agent#
| Operation | Title | Annotation |
|---|---|---|
agent.policy | Agent policy | read-only |
android#
| Operation | Title | Annotation |
|---|---|---|
android.screen | Android screen preview | writes |
android.store_screenshots | Capture store screenshots | writes |
android.input | Tap / swipe / input | writes |
android.hierarchy | Read UI tree | read-only |
android.launch | Start Android activity | writes |
android.record | Record display | writes |
android.mirror | Show Android live | writes |
android.deep_link | Open deep link | writes |
android.performance | Performance report | read-only |
android.ports | Connect dev server | writes |
android.permission | App permission | writes |
android.settings | Device settings for tests | writes |
android.display | Display orientation and size | writes |
android.notifications | Notifications | writes |
android.app_files | App data files | writes |
android.each | Run on every Android device | destructive |
android.connect | Android over Wi-Fi | writes |
android.pair | Pair over Wi-Fi by QR code | writes |
android.calibrate | Read model from device | writes |
android.sdk_packages | SDK packages | read-only |
android.sdk_install | Install SDK packages | writes |
android.avds | Android emulators | read-only |
android.avd_create | Create emulator | writes |
android.avd_profile | Set emulator display | destructive |
android.avd_configure | Set emulator performance | writes |
android.avd_start | Start emulator | writes |
android.emulator | Control emulator | destructive |
android.package_inspect | Inspect APK or AAB | read-only |
android.size_report | Report APK or AAB size | read-only |
android.sensors | Emulator sensors | writes |
android.app_links | App Links | writes |
android.network_capture | Network capture | writes |
apple#
| Operation | Title | Annotation |
|---|---|---|
apple.devices | Apple devices on the Mac | read-only |
apple.project | Read Xcode project | read-only |
apple.build | Build native iOS app | writes |
apple.test | Run XCTest / XCUITest | writes |
apple.archive | Create iOS archive | writes |
apple.export | Export and fetch IPA | writes |
apple.simulator | Control Apple Simulator | destructive |
apple.device | Control iPhone on the Mac | destructive |
apple.profile | Instruments recording | writes |
apple.store | Upload App Store build | writes |
audit#
| Operation | Title | Annotation |
|---|---|---|
audit.list | Audit log | read-only |
catalog#
| Operation | Title | Annotation |
|---|---|---|
catalog.list | Device catalog | read-only |
catalog.import | Import models | writes |
catalog.export | Export model | writes |
catalog.remove | Remove custom model | destructive |
debug#
| Operation | Title | Annotation |
|---|---|---|
debug.start | Start debugger | writes |
debug.list | Debug sessions | read-only |
debug.state | Debugger status | read-only |
debug.events | Debugger events | read-only |
debug.breakpoints | Set breakpoints | writes |
debug.threads | Read threads | read-only |
debug.stack | Read call stack | read-only |
debug.variables | Read variables | read-only |
debug.evaluate | Evaluate expression | writes |
debug.control | Control debugger | writes |
desktop#
| Operation | Title | Annotation |
|---|---|---|
desktop.status | Desktop status | read-only |
desktop.open | Open Tomacco | writes |
device#
| Operation | Title | Annotation |
|---|---|---|
device.list | Find devices | read-only |
device.info | Device information | read-only |
device.label | Name or pin a device | writes |
device.install | Install app | destructive |
device.app | Control app | destructive |
device.screenshot | Device screenshot | writes |
device.capture | Device image for agents | writes |
device.logs | Device logs | writes |
diagnostics#
| Operation | Title | Annotation |
|---|---|---|
diagnostics.bundle | Write a bug report bundle | writes |
files#
| Operation | Title | Annotation |
|---|---|---|
files.list | Show project files | read-only |
files.read | Open source file | read-only |
files.write | Save source file | destructive |
files.mkdir | Create project folder | writes |
files.search | Search project | read-only |
ios#
| Operation | Title | Annotation |
|---|---|---|
ios.sdk_install | Import Apple SDK | writes |
ios.toolkit_install | Install iOS toolkit | writes |
ios.flutter_setup | Prepare Flutter for iOS | writes |
ios.flutter_build | Build Flutter app for iOS | writes |
ios.crash_symbolicate | Read crash report | writes |
ios.ipa_inspect | Inspect iOS app | read-only |
ios.store_ship | Prepare for App Store | writes |
ios.doctor | Check iPhone development on Linux | read-only |
ios.prepare | Set up iPhone connection | writes |
ios.device_status | iPhone readiness | read-only |
ios.wda_prepare | Prepare iPhone control | writes |
ios.apps | Show iPhone apps | read-only |
ios.app_files | iPhone app files | writes |
ios.record | Record iPhone screen | writes |
ios.crash_reports | iPhone crash reports | writes |
ios.signing | iPhone signing overview | read-only |
ios.emulator.inspect | Check iOS emulator | read-only |
ios.emulator.probe | Examine iOS kernel boot | writes |
ios.emulator.exec | Run iOS guest command | writes |
ios.emulator.restore | Restore virtual iOS system | destructive |
ios.emulator.usb_bridge | Start virtual iOS USB access | writes |
ios.emulator.paravirtual | Start virtual iOS platform | writes |
ios.emulator.control | Operate running virtual iOS | writes |
ios.emulator.build_gpu_plugin | Build iOS graphics compiler plugin | writes |
ios.emulator.prepare_userland | Import original iOS system | writes |
ios.emulator.prepare_restore | Prepare virtual iOS restore runtime | writes |
ios.emulator.build_guest_tools | Build native iOS guest tools | writes |
ios.emulator.prepare_guest_tools | Install native iOS guest tools | writes |
ios.emulator.guest | Control native iOS guest programs | writes |
ios.emulator.guest_result | Fetch result of an iOS guest job | read-only |
ios.emulator.prepare_cryptexes | Install iOS cryptex files | writes |
ios.emulator.prepare_research | Prepare iOS test system | writes |
ios.emulator.prepare_pmp | Prepare PMP firmware | writes |
ios.emulator.inspect_pmp | Check PMP execution | read-only |
ios.emulator.pmp | Run PMP firmware | writes |
ios.emulator.research | Start iOS test run | writes |
ios.emulator.report | Read iOS test run | read-only |
ios.emulator.memory | Read PMP memory | read-only |
ios.virtual.status | Virtual iOS device: status | read-only |
ios.virtual.host_check | Check this machine for the virtual iOS device | read-only |
ios.virtual.doctor | Check the virtual iOS device | read-only |
ios.virtual.setup | Set up the virtual iOS device | writes |
ios.virtual.configure | Set up virtual iOS device | writes |
ios.virtual.profiles | Profiles of virtual iOS device | read-only |
ios.virtual.apps | Apps of virtual iOS device | read-only |
ios.virtual.start | Start virtual iOS device | writes |
ios.virtual.stop | Stop virtual iOS device | writes |
ios.virtual.unlock | Unlock virtual iOS device | writes |
ios.virtual.cleanup | Clean up virtual iOS device disk copies | destructive |
ios.virtual.states | Saved states of virtual iOS device | read-only |
ios.virtual.state_save | Save state of virtual iOS device | writes |
ios.virtual.state_delete | Delete saved state of virtual iOS device | destructive |
ios.virtual.state_use | Start virtual iOS device from saved state | writes |
ios.virtual.deploy | Install app on running virtual iOS device | writes |
ios.virtual.debug | Debug process on virtual iOS device | writes |
ios.virtual.crash_reports | Save crash reports of virtual iOS device | writes |
ios.virtual.syslog | Log of virtual iOS device | read-only |
ios.virtual.screenshot | Screenshot of virtual iOS device | writes |
ios.virtual.record | Record virtual iOS device screen | writes |
job#
| Operation | Title | Annotation |
|---|---|---|
job.list | Jobs | read-only |
job.get | Job status | read-only |
job.logs | Live logs | read-only |
job.wait | Wait for job | read-only |
job.events | Job timeline | read-only |
job.cancel | Cancel job | destructive |
job.send | Send a command to a job | writes |
play#
| Operation | Title | Annotation |
|---|---|---|
play.prepare | Prepare Google Play release | writes |
play.commit | Commit Google Play change | destructive |
play.abort | Discard Google Play draft | destructive |
preview#
| Operation | Title | Annotation |
|---|---|---|
preview.sessions | Preview sessions | read-only |
preview.state | Preview status | read-only |
preview.navigate | Open URL | writes |
preview.configure | Configure preview | writes |
preview.evaluate | Run JavaScript | writes |
preview.capture | Capture preview | writes |
preview.inspect | Inspect DOM | read-only |
preview.console | Browser console | read-only |
preview.errors | Page errors | writes |
preview.click | Click element | writes |
preview.fill | Fill in form | writes |
preview.reload | Reload page | writes |
preview.catalog_reload | Reload catalog | writes |
preview.audit | Check layout | read-only |
preview.ready | Wait for rendering | read-only |
preview.matrix | Capture device matrix | writes |
profile#
| Operation | Title | Annotation |
|---|---|---|
profile.capture | Capture Android profile | writes |
profile.analyze | Analyze performance profile | writes |
profile.compare | Compare performance reports | writes |
profile.startup | Measure app startup | writes |
profile.frames | Measure frame rendering | writes |
profile.memory | Measure app memory | writes |
profile.usage | Measure CPU and battery use | writes |
profile.budget | Check performance budget | writes |
profile.macrobenchmark | Run Macrobenchmark | writes |
profile.benchmark_results | Read Macrobenchmark results | read-only |
profile.baseline_profile | Generate Baseline Profile | writes |
profile.baseline_rules | Read Baseline Profile rules | read-only |
profile.baseline_install | Install Baseline Profile | destructive |
profile.baseline_compare | Compare startup with and without Baseline Profile | writes |
project#
| Operation | Title | Annotation |
|---|---|---|
project.inspect | Open project | read-only |
project.configure | Configure project | destructive |
project.create | Create project | writes |
project.plan | View build plan | read-only |
project.execute | Start build / test | writes |
project.run | Build & run on device | writes |
project.watch | Watch and rerun app | writes |
project.dependency_updates | Check dependency updates | read-only |
project.analyze | Analyze project code | read-only |
project.import_xcode | Import Xcode project | writes |
project.app | Find built iOS app | read-only |
release#
| Operation | Title | Annotation |
|---|---|---|
release.keystore | Create signing key | writes |
release.sign | Sign Android release | writes |
release.verify | Verify release signature | read-only |
release.signing_health | Check signing keys | read-only |
release.version | Set app version | destructive |
release.notes | Write Play release notes | destructive |
release.checklist | Check Android release readiness | read-only |
remote#
| Operation | Title | Annotation |
|---|---|---|
remote.list | Mac workspaces | read-only |
remote.configure | Connect Mac | writes |
remote.check | Check Mac | read-only |
remote.sync | Transfer project to Mac | writes |
remote.run | Run on Mac | destructive |
remote.fetch | Download Mac artifact | writes |
result#
| Operation | Title | Annotation |
|---|---|---|
result.read | Read a saved result | read-only |
runtime#
| Operation | Title | Annotation |
|---|---|---|
runtime.start | Connect native runtime | writes |
runtime.list | Native sessions | read-only |
runtime.audio | Stream device audio | writes |
runtime.state | Runtime status | read-only |
runtime.stop | Disconnect runtime | writes |
runtime.input | Native input | writes |
runtime.capture | Native capture | writes |
runtime.hierarchy | Native accessibility tree | read-only |
screen#
| Operation | Title | Annotation |
|---|---|---|
screen.marks | Mark tappable elements | writes |
screen.tap | Tap a mark | writes |
screen.tree | Read UI tree as text | writes |
screen.ocr | Read text on screen | read-only |
screen.diff | Compare two screens | read-only |
screen.wait | Wait for text or a steady screen | read-only |
screen.export | Export a screen | writes |
screen.export_batch | Export screens of several devices | writes |
settings#
| Operation | Title | Annotation |
|---|---|---|
settings.get | Settings | read-only |
settings.configure | Set up toolchain | writes |
storage#
| Operation | Title | Annotation |
|---|---|---|
storage.prune | Clean up old jobs and reports | destructive |
swift#
| Operation | Title | Annotation |
|---|---|---|
swift.status | Swift toolchain | read-only |
swift.android_configure | Connect Swift to the Android NDK | writes |
swift.sdk_install | Install Swift SDK | writes |
swift.plan | Plan Swift build | read-only |
swift.execute | Compile / test Swift | writes |
testing#
| Operation | Title | Annotation |
|---|---|---|
testing.find | Find Android element | read-only |
testing.action | Operate Android element | writes |
testing.run | Run native tests | writes |
testing.record | Record UI test | writes |
testing.lint | Check UI test scenario | read-only |
testing.visual_diff | Compare with baseline image | writes |
testing.accessibility | Check Android accessibility | read-only |
testing.crashes | Find app crashes | read-only |
testing.results | Read test results | read-only |
testing.coverage | Read code coverage | read-only |
testing.report | Write HTML test report | writes |
testing.history | Test pass-rate history | writes |
testing.impact | Select affected tests | writes |
testing.baselines | Review screenshot baselines | destructive |
testing.setup | Set up Android text input | writes |
testing.instrumentation | Check Android text input | read-only |
update#
| Operation | Title | Annotation |
|---|---|---|
update.check | Check for updates | read-only |
update.apply | Install update | destructive |
update.status | Update status | read-only |
update.rollback | Roll back update | destructive |
workflow#
| Operation | Title | Annotation |
|---|---|---|
workflow.run | Run steps in order | destructive |
workspace#
| Operation | Title | Annotation |
|---|---|---|
workspace.list | Read workspaces | read-only |
workspace.save | Save workspace | writes |
workspace.remove | Remove workspace | destructive |
workspace.context | Load agent context | read-only |
workspace.execute | Run workspace | writes |