MCP tool reference
Last updated:Nov 13, 2026
yunyoo MCP tools come in three forms that share one set of tools; a few tools and parameters differ between forms. The remote form is served at https://mcp.yunyoo.ai. The stdio cloud form is started with yunyoo mcp and works on environments on cloud and local nodes through the platform. The stdio local form is started with yunyoo mcp --local and works on the local node on this computer through the desktop app. For setting up each client, see MCP.
All tools are listed below in tool-list order. Where a description or parameter differs between forms, each form is shown separately. Tools outside a credential's scopes do not appear in its tool list.
Tools
device_list
List devices
remote, stdio cloud: Lists the devices you can operate: environment ID, name and status. Call it before you start, and pass an environment ID from the result as device in later calls, written as env:<environment ID>.
stdio local: Lists the environments this computer can reach: device reference ref, name, whether online, node and sync state. Call it before you start, and pass a ref as device in later calls.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
No parameters.
Fields in the result:
| Field | Description |
|---|---|
devices | The devices you can operate: in the cloud forms each has id, title and status; in the stdio local form each has ref, kind, name and online, plus node and sync |
device_use
Pick a device
remote: Checks that the device is available and returns a summary. Remote has no session, so later calls still need device.
stdio cloud: Picks this process's current device; later calls without device act on it. Call it once first when you only work on one device; device is written as env:<environment ID>.
stdio local: Picks this process's current device (env:<environment ID>); later calls without device act on it. Call it once first when you only work on one device.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | Yes | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Device: env:<environment ID> or an environment ID (device_list lists them) |
status
Automation status
remote, stdio cloud: Gets the device's automation state: whether it can be interacted with, its capabilities and its control state. Call it before acting or when an action fails, and use the capabilities to decide which actions are available (without textInput, only ASCII can be typed)
stdio local: Gets the desktop app local API's version, capabilities and online state; call it first when you cannot reach a device or an action fails.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Returns: In the cloud forms, the device's automation state; in the stdio local form, the desktop app local API's version, capabilities and online state.
| Field | Description |
|---|---|
capabilities | Capabilities, such as textInput and refIdentity |
control | Control state: free, automating, human or waiting-human |
degraded | Whether this is the degraded tier |
device | The device, written as env:<environment ID> |
flavor | Stdio local form: the desktop app's flavor |
interactable | Whether the device can be interacted with now |
online | Stdio local form: whether the desktop app is online |
protocol | Automation protocol version |
version | Stdio local form: the desktop app's version |
ui_inspect
Read UI elements
remote, stdio cloud: Reads the device's current screen. Returns a compact snapshot by default: the first line has the snapshot version, the screen and the foreground app, followed by one element per line (ID, class name, text, description, resource ID, center coordinates and state). Call it before acting and locate elements by their IDs or text. format=json returns a structured tree, scope=all lists every element and under shows only the subtree of one element.
stdio local: Reads the current screen of the device (an environment this computer can reach). Returns a compact snapshot by default, one element per line; call it before acting and locate elements by their IDs or text. format=json returns a structured tree. Older desktop apps only return the structured tree.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
all | boolean | No | Also include off-screen and invisible elements |
depth | integer | No | How many levels to list below the starting point, 1–100 |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
format | string | No | compact (default) or json |
max | integer | No | Maximum number of elements to list, 1–2000, default 150 |
scope | string | No | interactive (default, only elements that can be interacted with or have text) or all (list every element) |
under | string | No | Only list the subtree under this element ID |
ui_find
Find UI elements
remote, stdio cloud: Finds elements on the current screen by text, regex, resource ID, description or class name; all conditions must match. When the screen has many elements and you only care about a few, use it instead of ui_inspect. Returns the compact lines of the matches and suggested selectors that are unique on the current screen (usable in flows), or an empty result when nothing matches.
stdio local: Finds elements on the current screen of the device (an environment this computer can reach) by text, regex, resource ID, description or class name. When the screen has many elements and you only care about a few, use it instead of ui_inspect. Returns the compact lines of the matches and unique suggested selectors. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
all | boolean | No | Also search off-screen and invisible elements |
class | string | No | Class name; the package name can be left out |
desc | string | No | Description contains this, case-insensitive |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
id | string | No | Resource ID; the package name can be left out |
max | integer | No | Maximum number of matches to return, 1–100, default 20 |
regex | string | No | Regex matched against the text or description |
text | string | No | Text contains this, case-insensitive |
screenshot
Screenshot. Takes a screenshot of the device and returns a compressed image (JPEG with a 1024-pixel long edge by default) with the original resolution and the scale. Use it when the UI structure cannot show the content (images, video, game screens). annotate marks the element IDs from the latest ui_inspect on the image; max_edge, format and quality control the size and quality.
Forms: remote, stdio cloud, stdio local; read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
annotate | boolean | No | Mark the element IDs from the latest ui_inspect on the image |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
format | string | No | Image format: jpeg (default) or png |
max_edge | integer | No | Long edge in pixels, 256–2048, default 1024 |
quality | integer | No | JPEG quality, 1–100, default 75 |
ui_tap
Tap. Taps an element on the device. Locate it by element ID (with its snapshot version), resource ID, text or description, and use the normalized coordinates x and y only when no element is available. A long_press_ms greater than 0 long-presses. effect in the result says whether the screen changed. Do not tap buttons that pay, transfer money, place an order or change account and security settings; hand them to the user with handoff, even when the user says not to ask. Taps the platform judges high-risk may be held first and return a confirmation.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
desc | string | No | Description selector |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
element | string | No | Element ID (the elementId returned by ui_inspect) |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
long_press_ms | integer | No | Long-press duration in milliseconds; a single tap when omitted |
resource_id | string | No | Resource ID selector |
snapshot | integer | No | remote: Snapshot version the element belongs to (the snapshot returned by ui_inspect; required with element); stdio: Snapshot version the element belongs to (the snapshot returned by ui_inspect; defaults to the version from this process's latest ui_inspect on the device) |
text | string | No | Text selector |
verify | boolean | No | Checks whether the action took effect, on by default: effect in the result is changed or unchanged. When off, the action is only dispatched and effect is unverified |
x | number | No | Normalized x coordinate, used when no element is available (0..1) |
y | number | No | Normalized y coordinate, used when no element is available (0..1) |
Returns: The result of the UI action.
| Field | Description |
|---|---|
activity | Foreground activity after the action |
candidates | Candidate elements when the target is not unique |
device | The device, written as env:<environment ID> |
effect | Effect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked |
error_code | Error code when it did not complete |
matched | Whether the wait found its target |
message | Why it did not complete |
ok | Whether the action completed |
package | Package name of the foreground app after the action |
snapshot_version | Snapshot version after the action |
target | The element actually acted on: ID, class name, resource ID, text, description and bounds |
timed_out | Whether the wait timed out |
ui_swipe
Swipe. Swipes from one point to another on the device (normalized coordinates, 0..1) to turn pages, scroll lists or pull to refresh. from_x and from_y are the start, to_x and to_y the end, and duration_ms the swipe duration.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
duration_ms | integer | No | remote: Swipe duration in milliseconds (default 300); stdio: Swipe duration in milliseconds (default 300) |
from_x | number | Yes | |
from_y | number | Yes | |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
to_x | number | Yes | |
to_y | number | Yes | |
verify | boolean | No | Checks whether the action took effect, on by default: effect in the result is changed or unchanged. When off, the action is only dispatched and effect is unverified |
Returns: The result of the UI action.
| Field | Description |
|---|---|
activity | Foreground activity after the action |
candidates | Candidate elements when the target is not unique |
device | The device, written as env:<environment ID> |
effect | Effect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked |
error_code | Error code when it did not complete |
matched | Whether the wait found its target |
message | Why it did not complete |
ok | Whether the action completed |
package | Package name of the foreground app after the action |
snapshot_version | Snapshot version after the action |
target | The element actually acted on: ID, class name, resource ID, text, description and bounds |
timed_out | Whether the wait timed out |
ui_type
Type text. Types text into the focused input field (or the element given by element). clear clears it first and submit presses Enter afterwards. Without the textInput capability, only ASCII can be typed. Do not type passwords, verification codes or payment details for the user; hand the step to the user with handoff.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
clear | boolean | No | Clear before typing |
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
element | string | No | Target element ID (defaults to the focused one) |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
snapshot | integer | No | remote: Snapshot version the element belongs to (the snapshot returned by ui_inspect; required with element); stdio: Snapshot version the element belongs to (defaults to the version from this process's latest ui_inspect on the device) |
submit | boolean | No | Press Enter after typing (to submit a search or a form) |
text | string | Yes | remote: The text to type; stdio: The text to type; only ASCII is supported when the device's capabilities do not include textInput |
verify | boolean | No | Checks whether the action took effect, on by default: effect in the result is changed or unchanged. When off, the action is only dispatched and effect is unverified |
Returns: The result of the UI action.
| Field | Description |
|---|---|
activity | Foreground activity after the action |
candidates | Candidate elements when the target is not unique |
device | The device, written as env:<environment ID> |
effect | Effect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked |
error_code | Error code when it did not complete |
matched | Whether the wait found its target |
message | Why it did not complete |
ok | Whether the action completed |
package | Package name of the foreground app after the action |
snapshot_version | Snapshot version after the action |
target | The element actually acted on: ID, class name, resource ID, text, description and bounds |
timed_out | Whether the wait timed out |
ui_key
Press a key. Sends a key to the device; code is an Android key code (66 Enter, 4 Back, 3 Home, 67 Delete)
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
code | integer | Yes | Android key code |
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
verify | boolean | No | Checks whether the action took effect, on by default: effect in the result is changed or unchanged. When off, the action is only dispatched and effect is unverified |
Returns: The result of the UI action.
| Field | Description |
|---|---|
activity | Foreground activity after the action |
candidates | Candidate elements when the target is not unique |
device | The device, written as env:<environment ID> |
effect | Effect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked |
error_code | Error code when it did not complete |
matched | Whether the wait found its target |
message | Why it did not complete |
ok | Whether the action completed |
package | Package name of the foreground app after the action |
snapshot_version | Snapshot version after the action |
target | The element actually acted on: ID, class name, resource ID, text, description and bounds |
timed_out | Whether the wait timed out |
ui_wait
Wait for an element. Waits for a condition to hold, to confirm the previous step's result: an element appears (selectors as in ui_tap), gone for an element to disappear, idle_ms for the screen to stay unchanged, animation for animations to end, or package for an app to come to the foreground. Wait for one condition at a time; timeout_ms is the limit (30 seconds at most per call; call again to wait longer), and a timeout returns 1003.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
activity | string | No | Use with package: wait for this activity to be in the foreground |
animation | boolean | No | Wait for animations to end |
desc | string | No | Description selector |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
element | string | No | Element ID (the elementId returned by ui_inspect) |
gone | object | No | Wait for this element to disappear; written like the selector for appearing, such as {"text":"Loading"} |
idle_ms | integer | No | Wait until the screen stays unchanged for this many milliseconds (default 800) |
package | string | No | Wait for this app to come to the foreground |
resource_id | string | No | Resource ID selector |
snapshot | integer | No | remote: Snapshot version the element belongs to (the snapshot returned by ui_inspect; required with element); stdio: Snapshot version the element belongs to (the snapshot returned by ui_inspect; defaults to the version from this process's latest ui_inspect on the device) |
text | string | No | Text selector |
timeout_ms | integer | No | Wait limit in milliseconds (default 5000, 30000 at most) |
x | number | No | Normalized x coordinate, used when no element is available (0..1) |
y | number | No | Normalized y coordinate, used when no element is available (0..1) |
Returns: The result of the UI action.
| Field | Description |
|---|---|
activity | Foreground activity after the action |
candidates | Candidate elements when the target is not unique |
device | The device, written as env:<environment ID> |
effect | Effect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked |
error_code | Error code when it did not complete |
matched | Whether the wait found its target |
message | Why it did not complete |
ok | Whether the action completed |
package | Package name of the foreground app after the action |
snapshot_version | Snapshot version after the action |
target | The element actually acted on: ID, class name, resource ID, text, description and bounds |
timed_out | Whether the wait timed out |
ui_batch
Batch actions
remote: Submits several UI and app actions at once and runs them step by step; use it for known, fixed steps. Steps have the same structure as the yunyoo.flow/2 flow format, up to 50 steps and 60 seconds. By default it stops at the first failure and returns per-step results and where it failed; when a confirmation is needed it returns the confirmation and where to resume (from, at, sub). Secret placeholders are not supported remotely.
stdio cloud: Submits several UI and app actions at once and runs them step by step; use it for known, fixed steps. Steps have the same structure as the yunyoo.flow/2 flow format, up to 50 steps and 60 seconds. By default it stops at the first failure and returns per-step results and where it failed; when a confirmation is needed it returns the confirmation and where to resume (from, at, sub)
stdio local: Submits several UI and app actions at once; the desktop app runs them step by step on the device (an environment this computer can reach). Use it for known, fixed steps. Steps have the same structure as the yunyoo.flow/2 flow format, up to 50 steps and 60 seconds. By default it stops at the first failure and returns per-step results and where it failed; when a confirmation is needed it returns the confirmation and where to resume. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
at | string | No | Position of the paused step, from pause.path in the previous result |
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
from | integer | No | Step to start from (from 1), used when resuming after a confirmation or a deviation |
inspect_at_end | boolean | No | Attach a compact snapshot at the end |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
keep_going | boolean | No | Keep running the later steps after a step fails or deviates |
steps | object[] | Yes | remote: Step list, such as [{"tapOn":"Search"},{"inputText":"${QUERY}"}]; stdio: Step list with the same structure as yunyoo.flow/2 flow steps, such as [{"tapOn":"Sign in"},{"back":{}}]; up to 50 steps and 60 seconds |
sub | integer | No | Which controlled action within the paused step, from pause.sub in the previous result |
vars | object | No | remote: Variable values, keyed by variable name; stdio: Variable values, keyed by variable name; any not given are read from the environment variable YUNYOO_VAR_<NAME> |
Returns: The batch's run report.
| Field | Description |
|---|---|
code | Error code when it did not pass |
confirmation | The confirmation waiting for approval |
deviation | Deviation report: step position, expected element, a summary of the current screen and similar elements |
device | The device, written as env:<environment ID> |
failed | The first failed step |
inspect | Compact snapshot at the end |
message | Why it did not pass |
pause | Where it paused for a confirmation (path and sub); pass it when resuming |
resume | Step to resume from |
runId | Run ID |
status | passed, failed, deviated, paused, cancelled or limited |
steps | Per-step results |
app_list
List apps
remote, stdio cloud: Lists the apps installed on the device: package names and readable names. Use it to confirm a package name before launching, stopping or uninstalling. When the platform list is unavailable, it lists on the device instead, leaves names empty and says so in note.
stdio local: Lists the apps installed on the device (listed on the device, package names only). Use it to confirm a package name before launching, stopping or uninstalling.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Fields in the result:
| Field | Description |
|---|---|
apps | Installed apps: package names and readable names |
device | The device, written as env:<environment ID> |
note | |
output | The raw output when listing on the device instead, one package:name per line |
source | Where the list comes from |
app_launch
Launch an app. Launches an app into the foreground; package is the package name (see app_list). Sensitive apps on the list may need the user's confirmation first.
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
package | string | Yes | App package name |
Returns: The result of the app operation.
| Field | Description |
|---|---|
channel | Execution channel |
device | The device, written as env:<environment ID> |
durationMs | |
exitCode | Exit code |
invokeId | |
outputBytes | |
status | succeeded, failed or timed_out |
stderr | Device error output |
stderrTruncated | |
stdout | Device output |
stdoutTruncated | |
taskId |
app_stop
Stop an app. Force-stops an app; package is the package name. Use it when the app is stuck or you want to start over.
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
package | string | Yes | App package name |
Returns: The result of the app operation.
| Field | Description |
|---|---|
channel | Execution channel |
device | The device, written as env:<environment ID> |
durationMs | |
exitCode | Exit code |
invokeId | |
outputBytes | |
status | succeeded, failed or timed_out |
stderr | Device error output |
stderrTruncated | |
stdout | Device output |
stdoutTruncated | |
taskId |
app_install
Install apps
remote, stdio cloud: Installs apps from the app library; app_ids are app IDs in the app library. Returns an install task; track it with job_get.
stdio local: Installs an app on the device: path is the path of an installer on this computer (only for environments on local nodes), or app_ids are app IDs in the app library (forwarded to the platform by the desktop app, which waits for the result)
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
app_ids | integer[] | required in the remote form | App IDs in the app library |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
path | string | No | Path of an installer on this computer; only in the stdio local form; only in the stdio form |
Returns: The result of the app install.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
hint | |
items | Stdio local form: the install result for each app |
ok | Stdio local form: whether the desktop app has finished |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
taskId | Stdio local form: the task ID when the desktop app forwarded the request to the platform |
app_uninstall
Uninstall an app. Uninstalls an app; keep_data keeps its data. This is a high-risk action and returns a confirmation when the user needs to approve.
Forms: remote, stdio cloud, stdio local; destructive; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
keep_data | boolean | No | Keep the app's data |
package | string | Yes | App package name |
Returns: The result of the app operation.
| Field | Description |
|---|---|
channel | Execution channel |
device | The device, written as env:<environment ID> |
durationMs | |
exitCode | Exit code |
invokeId | |
outputBytes | |
status | succeeded, failed or timed_out |
stderr | Device error output |
stderrTruncated | |
stdout | Device output |
stdoutTruncated | |
taskId |
app_clear
Clear app data. Clears all of an app's data, returning it to a freshly installed state. This is a high-risk action and returns a confirmation when the user needs to approve.
Forms: remote, stdio cloud, stdio local; destructive; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
package | string | Yes | App package name |
Returns: The result of the app operation.
| Field | Description |
|---|---|
channel | Execution channel |
device | The device, written as env:<environment ID> |
durationMs | |
exitCode | Exit code |
invokeId | |
outputBytes | |
status | succeeded, failed or timed_out |
stderr | Device error output |
stderrTruncated | |
stdout | Device output |
stdoutTruncated | |
taskId |
file_push
Push a file
remote: Pushes a file to the device's download folder: name is the file name and content_base64 the file content in base64 (up to 2 MB). Returns a push task; track it with job_get.
stdio cloud: Pushes a file from this computer to the device's download folder: local_path is the path on this computer and name the file name on the device (defaults to the local file name). Returns a push task.
stdio local: Pushes a file from this computer to the device's download folder (/sdcard/Download); local_path is the path on this computer and name can only be a file name.
Forms: remote, stdio cloud, stdio local; destructive; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
content_base64 | string | Yes | File content in base64; only in the remote form |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
name | string | required in the remote form | remote: File name; stdio: File name on the device (in the download folder); defaults to the local file name |
local_path | string | Yes | Path of the file on this computer; only in the stdio form |
Returns: The result of the file push.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
hint | |
ok | Stdio local form: whether the desktop app has finished |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
taskId | Stdio local form: the task ID when the desktop app forwarded the request to the platform |
file_pull
Fetch a file
remote: Fetches a file from the device; path is its path on the device. Returns a task; once it finishes, job_get gives a download link valid for 15 minutes.
stdio cloud: Fetches a file from the device; path is its path on the device. Returns a task; check progress with job_get and download the file from the web or desktop app when it finishes.
stdio local: Fetches a file from the device; path is its path on the device, written to local_path on this computer.
Forms: remote, stdio cloud, stdio local; read-only.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
path | string | Yes | Path of the file on the device |
local_path | string | No | Where to save it on this computer; required in the stdio local form. In the cloud forms, get the download link with job_get after the fetch; only in the stdio form |
Returns: The result of the file fetch.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
hint | |
ok | Stdio local form: whether the desktop app has finished |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
taskId | Stdio local form: the task ID when the desktop app forwarded the request to the platform |
env_start
Start
remote, stdio cloud: Starts the environment. When a task ID is returned, track progress with job_get. Starting takes a few minutes; act on it once status shows it can be interacted with.
stdio local: Starts the environment (forwarded to the platform by the desktop app). Starting takes a few minutes; check with device_list that it is online before acting on it.
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Returns: The result of the environment lifecycle operation.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
op | start, stop, reboot, pause, resume or sync |
result | The raw result returned by the platform or the desktop app |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
env_resume
Resume
remote, stdio cloud: Resumes a paused environment; when a task ID is returned, track progress with job_get.
stdio local: Resumes a paused environment (forwarded to the platform by the desktop app)
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Returns: The result of the environment lifecycle operation.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
op | start, stop, reboot, pause, resume or sync |
result | The raw result returned by the platform or the desktop app |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
env_stop
Shut down
remote, stdio cloud: Shuts down. The environment may still be stopping when the call returns; check with device_list that it has stopped before doing anything that needs it shut down (such as restoring a backup). When a task ID is returned, track progress with job_get.
stdio local: Shuts down (forwarded to the platform by the desktop app). The environment may still be stopping when the call returns; check with device_list that it has stopped before doing anything that needs it shut down.
Forms: remote, stdio cloud, stdio local; destructive; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Returns: The result of the environment lifecycle operation.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
op | start, stop, reboot, pause, resume or sync |
result | The raw result returned by the platform or the desktop app |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
env_pause
Pause
remote, stdio cloud: Pauses the environment and keeps its memory state; only for environments on local nodes. Continue with env_resume.
stdio local: Pauses the environment and keeps its memory state; only for environments on local nodes (forwarded to the platform by the desktop app). Continue with env_resume.
Forms: remote, stdio cloud, stdio local; destructive; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Returns: The result of the environment lifecycle operation.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
op | start, stop, reboot, pause, resume or sync |
result | The raw result returned by the platform or the desktop app |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
env_reboot
Reboot
remote, stdio cloud: Reboots the environment; use it when the screen is stuck or a setting needs a restart to take effect.
stdio local: Reboots the environment (forwarded to the platform by the desktop app); use it when the screen is stuck or a setting needs a restart to take effect.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Returns: The result of the environment lifecycle operation.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
op | start, stop, reboot, pause, resume or sync |
result | The raw result returned by the platform or the desktop app |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
env_sync
Sync to the cloud
remote, stdio cloud: Syncs the data of an environment on a local node to the cloud; stop shuts it down first.
stdio local: Syncs the data of an environment on a local node to the cloud (forwarded to the platform by the desktop app); stop shuts it down first.
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
stop | boolean | No | If it is running or paused, shut it down first and then sync |
Returns: The result of the environment lifecycle operation.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
op | start, stop, reboot, pause, resume or sync |
result | The raw result returned by the platform or the desktop app |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
backup_list
List backups
remote, stdio cloud: Lists the environment's backups: ID, name, type and status. Use it to find a backup ID before restoring.
stdio local: Lists the environment's backups (forwarded to the platform by the desktop app): ID, name, type and status. Use it to find a backup ID before restoring.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
Fields in the result:
| Field | Description |
|---|---|
backups | |
device | The device, written as env:<environment ID> |
backup_create
Create a backup
remote, stdio cloud: Creates a backup of the environment: with package, only that app's data is backed up; otherwise it is a full backup. name is the backup name.
stdio local: Creates a backup of the environment (forwarded to the platform by the desktop app): with package, only that app's data is backed up; otherwise it is a full backup.
Forms: remote, stdio cloud, stdio local.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
name | string | No | Name of the full backup |
package | string | No | App package name: make an app backup of this app only |
Returns: Backup record.
| Field | Description |
|---|---|
appPackage | Package name of an app backup |
createdAt | Creation time |
device | The device, written as env:<environment ID> |
envId | |
id | Backup ID |
kind | full is a full backup; app-sandbox is an app backup |
name | |
purpose | sync is a sync copy, migrate is a migration backup, and empty is a user backup |
status |
backup_restore
Restore a backup
remote, stdio cloud: Restores from one of the environment's backups; backup_id comes from backup_list. A full backup is restored at the next start, and an app backup restores that app right away. This is a high-risk action and returns a confirmation when the user needs to approve.
stdio local: Restores from one of the environment's backups (forwarded to the platform by the desktop app); backup_id comes from backup_list. An app backup restores that app right away. This is a high-risk action and returns a confirmation when the user needs to approve.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
backup_id | integer | Yes | Backup ID |
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
ignore_version | boolean | No | Skip the version check for app restores |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
Returns: The result of the restore.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
hint | |
pending | Full backups: the backup to restore at the next start |
status | |
task | Platform task ID; check its progress and result with job_get |
taskId | Task ID of an app restore |
backup_share
Share a backup package
remote, stdio cloud: Creates a share link for the environment's backup package; claiming always requires signing in. package_id is the package ID, expires_hours the number of hours it stays valid (default 24) and max_downloads the maximum number of downloads (default 5). Returns a confirmation when the user needs to approve.
stdio local: Creates a share link for the environment's backup package (forwarded to the platform by the desktop app); claiming always requires signing in. Returns a confirmation when the user needs to approve.
Forms: remote, stdio cloud, stdio local.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
expires_hours | integer | No | Hours it stays valid (default 24) |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
max_downloads | integer | No | Maximum number of downloads (default 5) |
package_id | string | Yes | Package ID |
Returns: Share link.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
expiresAt | Expiry time |
shareId | |
shareUrl | Share link; claiming requires signing in |
token |
job_get
Get task
remote: Gets the status and result of a platform async task (power, backups, file transfers, app installs, flows); task is the task ID. When a file fetch has finished and you have the file download permission, a download link valid for 15 minutes is included.
stdio cloud: Gets the status and result of a platform async task (power, backups, file transfers, app installs, flows); task is the task ID.
stdio local: Gets the status and result of a local flow task (the job_ ID returned by macro_run). Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
task | string | Yes | remote: Task ID; stdio: Task ID: platform tasks are numbers, local flow tasks start with job_ |
Returns: The task's status and result.
| Field | Description |
|---|---|
ID | Platform task ID |
device | The device, written as env:<environment ID> |
expiresIn | How many seconds the download link stays valid |
job | Local flow task ID |
message | |
percent | |
result | Task result; for flows, the run report |
size | |
stage | |
status | Task status |
type | Task type |
url | The download link once the file has been fetched |
macro_run
Run a flow
remote: Runs a yunyoo.flow/2 flow; flow is the inline content. It is checked first and then runs as a platform async task, returning a task ID to track with job_get. When the run deviates, the task ends with 53019 and a deviation report. Secret placeholders are not supported remotely.
stdio cloud: Runs a yunyoo.flow/2 flow; flow is the inline content or file a file on this computer. It is checked first and then runs as an async task, returning a task ID to track with job_get. When the run deviates, the task ends with 53019 and a deviation report. Secret placeholders get their values on this computer (YUNYOO_SECRET_<name> or the keychain), and the values never appear in the result.
stdio local: Runs a yunyoo.flow/2 flow; flow is the inline content or file a file on this computer. It is checked first and then the desktop app runs it as a local flow task, returning a task ID (starting with job_) to track with job_get. Secret placeholders get their values on this computer (YUNYOO_SECRET_<name> or the keychain), and the values never appear in the result. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
at | string | No | Position of the paused step, from pause.path in the previous result |
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
flow | object | required in the remote form | remote: Flow content (schema yunyoo.flow/2); stdio: Flow content (schema yunyoo.flow/2); give either this or file |
from | integer | No | Step to start from (from 1), used when resuming after a confirmation or a deviation |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
sub | integer | No | Which controlled action within the paused step, from pause.sub in the previous result |
vars | object | No | remote: Variable values; take precedence over the env defaults in the flow; stdio: Variable values; take precedence over the environment variable YUNYOO_VAR_<NAME> and the env defaults in the flow |
file | string | No | Flow file on this computer (.json or .yaml); give either this or flow; only in the stdio form |
macro_save
Generate a macro draft
remote, stdio cloud: Generates a flow draft from a run record; run is the run ID (see run_report). Only successful actions are kept, and typed text that cannot be copied verbatim becomes a variable INPUT_n.
stdio local: Generates a flow draft from a run record; run is the run ID (see run_report). Only successful actions are kept, and typed text that cannot be copied verbatim becomes a variable INPUT_n. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
run | string | Yes | Run ID; see run_report |
run_report
Run report
remote, stdio cloud: Gets the report of a run: each step's tool, parameter summary, target element, effect check, result code and duration. Without run it uses the latest run; with device it only looks at that device.
stdio local: Gets the report of a run: each step's tool, parameter summary, target element, effect check, result code and duration. Without run it uses the latest run. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | No | Target device: env:<environment ID> or an environment ID; without run, only the latest run on this device |
run | string | No | Run ID |
confirm_wait
Wait for a confirmation
remote, stdio cloud: Waits for a decision on a confirmation (up to 60 seconds per call) and returns pending, approved, denied, expired, cancelled or executed. Call it after a tool returns 53010; once approved, call the held tool again with the same parameters plus confirmation_id.
stdio local: Waits for a decision on a confirmation (up to 60 seconds per call) and returns pending, approved, denied, expired, cancelled or executed. Call it after a tool returns 53010; once approved, call the tool again with the same parameters plus confirmation_id. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; read-only; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | Yes | Confirmation ID |
wait_ms | integer | No | Maximum wait in milliseconds, 0–60000, default 30000 |
Returns: The confirmation's status.
| Field | Description |
|---|---|
action | |
categories | Risk categories |
createdAt | Creation time |
decidedAt | When it was decided |
envId | |
executedAt | When it ran |
expiresAt | Expiry time |
id | Confirmation ID |
intent | |
status | pending, approved, denied, expired, cancelled or executed |
summary | Action summary |
url | Confirmation page URL |
confirm_cancel
Withdraw a confirmation
remote, stdio cloud: Withdraws a confirmation that is still pending; calling again with it afterwards returns 53011.
stdio local: Withdraws a confirmation that is still pending; calling again with it afterwards returns 53011. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
confirmation_id | string | Yes | Confirmation ID |
handoff
Hand off to a person
remote, stdio cloud: Asks the user to take over this device. Use it for payment, money transfers and placing orders, for typing passwords, verification codes or payment details, for changing account and security settings, and for CAPTCHAs, sign-in and other screens the person has to handle themselves, even when the user says not to ask; reason says why. During the handoff, action tools return 53014, and they work again once the user hands back in the viewer. Without reason, only the current state is returned.
stdio local: Asks the user to take over this device. Use it for payment, money transfers and placing orders, for typing passwords, verification codes or payment details, for changing account and security settings, and for CAPTCHAs, sign-in and other screens the person has to handle themselves, even when the user says not to ask; reason says why. During the handoff, action tools return 53014, and they work again once the user hands back. Without reason, only the current state is returned. Requires a recent desktop app.
Forms: remote, stdio cloud, stdio local; idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
reason | string | No | Why the user is needed; without it, only the current state is returned |
run_command
Run a command
remote: Runs a command on the device (an escape hatch that needs the run-command scope). Use it only when the UI and app tools cannot do the job. argv is the command and its arguments, and shell runs it through the shell. The local bridge is not offered in the remote form; use the connect command on the command line when you need it.
stdio cloud: Runs a command on the device (an escape hatch that needs the run-command scope). Use it only when the UI and app tools cannot do the job. argv is the command and its arguments, shell runs it through the shell, and timeout_ms is the time limit.
stdio local: Runs a command on the device (argv; the desktop app runs it directly for environments on local nodes, and forwards it to the platform for environments on cloud nodes, subject to the run-command scope). Use it only when the UI and app tools cannot do the job.
Forms: remote, stdio cloud, stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
argv | string[] | Yes | Command and arguments (argv) |
confirmation_id | string | No | ID of the confirmation the user approved after the call was held; call again with the same parameters plus this ID, and the action runs once |
device | string | required in the remote form | remote: Target device: env:<environment ID> or an environment ID (device_list lists them); stdio: Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
intent | string | No | What this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them |
shell | boolean | No | Run through the shell |
timeout_ms | integer | No | Run timeout in milliseconds |
connect
Local bridge. Sets up a local bridge (an escape hatch that needs the local-bridge scope). Use it only when no other tool can do the job.
Forms: stdio cloud.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | No | Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
env_power
Power and pause. Deprecated and removed in the next minor version; use env_start, env_stop, env_reboot, env_pause and env_resume instead. Starts, shuts down, reboots, pauses or resumes an environment (forwarded to the platform by the desktop app)
Forms: stdio local; destructive.
| Parameter | Type | Required | Description |
|---|---|---|---|
device | string | No | Target device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option |
op | string | Yes | start, stop, reboot, pause or resume |
Returns: The result of the environment lifecycle operation.
| Field | Description |
|---|---|
device | The device, written as env:<environment ID> |
op | start, stop, reboot, pause, resume or sync |
result | The raw result returned by the platform or the desktop app |
status | Task status |
task | Platform task ID; check its progress and result with job_get |
