yunyoo

Documentation

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:

FieldDescription
devicesThe 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.

ParameterTypeRequiredDescription
devicestringYesremote: 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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.

FieldDescription
capabilitiesCapabilities, such as textInput and refIdentity
controlControl state: free, automating, human or waiting-human
degradedWhether this is the degraded tier
deviceThe device, written as env:<environment ID>
flavorStdio local form: the desktop app's flavor
interactableWhether the device can be interacted with now
onlineStdio local form: whether the desktop app is online
protocolAutomation protocol version
versionStdio 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.

ParameterTypeRequiredDescription
allbooleanNoAlso include off-screen and invisible elements
depthintegerNoHow many levels to list below the starting point, 1–100
devicestringrequired in the remote formremote: 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
formatstringNocompact (default) or json
maxintegerNoMaximum number of elements to list, 1–2000, default 150
scopestringNointeractive (default, only elements that can be interacted with or have text) or all (list every element)
understringNoOnly 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.

ParameterTypeRequiredDescription
allbooleanNoAlso search off-screen and invisible elements
classstringNoClass name; the package name can be left out
descstringNoDescription contains this, case-insensitive
devicestringrequired in the remote formremote: 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
idstringNoResource ID; the package name can be left out
maxintegerNoMaximum number of matches to return, 1–100, default 20
regexstringNoRegex matched against the text or description
textstringNoText 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.

ParameterTypeRequiredDescription
annotatebooleanNoMark the element IDs from the latest ui_inspect on the image
devicestringrequired in the remote formremote: 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
formatstringNoImage format: jpeg (default) or png
max_edgeintegerNoLong edge in pixels, 256–2048, default 1024
qualityintegerNoJPEG 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.

ParameterTypeRequiredDescription
confirmation_idstringNoID 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
descstringNoDescription selector
devicestringrequired in the remote formremote: 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
elementstringNoElement ID (the elementId returned by ui_inspect)
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
long_press_msintegerNoLong-press duration in milliseconds; a single tap when omitted
resource_idstringNoResource ID selector
snapshotintegerNoremote: 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)
textstringNoText selector
verifybooleanNoChecks 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
xnumberNoNormalized x coordinate, used when no element is available (0..1)
ynumberNoNormalized y coordinate, used when no element is available (0..1)

Returns: The result of the UI action.

FieldDescription
activityForeground activity after the action
candidatesCandidate elements when the target is not unique
deviceThe device, written as env:<environment ID>
effectEffect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked
error_codeError code when it did not complete
matchedWhether the wait found its target
messageWhy it did not complete
okWhether the action completed
packagePackage name of the foreground app after the action
snapshot_versionSnapshot version after the action
targetThe element actually acted on: ID, class name, resource ID, text, description and bounds
timed_outWhether 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.

ParameterTypeRequiredDescription
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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_msintegerNoremote: Swipe duration in milliseconds (default 300); stdio: Swipe duration in milliseconds (default 300)
from_xnumberYes
from_ynumberYes
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
to_xnumberYes
to_ynumberYes
verifybooleanNoChecks 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.

FieldDescription
activityForeground activity after the action
candidatesCandidate elements when the target is not unique
deviceThe device, written as env:<environment ID>
effectEffect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked
error_codeError code when it did not complete
matchedWhether the wait found its target
messageWhy it did not complete
okWhether the action completed
packagePackage name of the foreground app after the action
snapshot_versionSnapshot version after the action
targetThe element actually acted on: ID, class name, resource ID, text, description and bounds
timed_outWhether 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.

ParameterTypeRequiredDescription
clearbooleanNoClear before typing
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
elementstringNoTarget element ID (defaults to the focused one)
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
snapshotintegerNoremote: 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)
submitbooleanNoPress Enter after typing (to submit a search or a form)
textstringYesremote: The text to type; stdio: The text to type; only ASCII is supported when the device's capabilities do not include textInput
verifybooleanNoChecks 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.

FieldDescription
activityForeground activity after the action
candidatesCandidate elements when the target is not unique
deviceThe device, written as env:<environment ID>
effectEffect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked
error_codeError code when it did not complete
matchedWhether the wait found its target
messageWhy it did not complete
okWhether the action completed
packagePackage name of the foreground app after the action
snapshot_versionSnapshot version after the action
targetThe element actually acted on: ID, class name, resource ID, text, description and bounds
timed_outWhether 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.

ParameterTypeRequiredDescription
codeintegerYesAndroid key code
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
verifybooleanNoChecks 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.

FieldDescription
activityForeground activity after the action
candidatesCandidate elements when the target is not unique
deviceThe device, written as env:<environment ID>
effectEffect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked
error_codeError code when it did not complete
matchedWhether the wait found its target
messageWhy it did not complete
okWhether the action completed
packagePackage name of the foreground app after the action
snapshot_versionSnapshot version after the action
targetThe element actually acted on: ID, class name, resource ID, text, description and bounds
timed_outWhether 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.

ParameterTypeRequiredDescription
activitystringNoUse with package: wait for this activity to be in the foreground
animationbooleanNoWait for animations to end
descstringNoDescription selector
devicestringrequired in the remote formremote: 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
elementstringNoElement ID (the elementId returned by ui_inspect)
goneobjectNoWait for this element to disappear; written like the selector for appearing, such as {"text":"Loading"}
idle_msintegerNoWait until the screen stays unchanged for this many milliseconds (default 800)
packagestringNoWait for this app to come to the foreground
resource_idstringNoResource ID selector
snapshotintegerNoremote: 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)
textstringNoText selector
timeout_msintegerNoWait limit in milliseconds (default 5000, 30000 at most)
xnumberNoNormalized x coordinate, used when no element is available (0..1)
ynumberNoNormalized y coordinate, used when no element is available (0..1)

Returns: The result of the UI action.

FieldDescription
activityForeground activity after the action
candidatesCandidate elements when the target is not unique
deviceThe device, written as env:<environment ID>
effectEffect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked
error_codeError code when it did not complete
matchedWhether the wait found its target
messageWhy it did not complete
okWhether the action completed
packagePackage name of the foreground app after the action
snapshot_versionSnapshot version after the action
targetThe element actually acted on: ID, class name, resource ID, text, description and bounds
timed_outWhether 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.

ParameterTypeRequiredDescription
atstringNoPosition of the paused step, from pause.path in the previous result
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
fromintegerNoStep to start from (from 1), used when resuming after a confirmation or a deviation
inspect_at_endbooleanNoAttach a compact snapshot at the end
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
keep_goingbooleanNoKeep running the later steps after a step fails or deviates
stepsobject[]Yesremote: 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
subintegerNoWhich controlled action within the paused step, from pause.sub in the previous result
varsobjectNoremote: 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.

FieldDescription
codeError code when it did not pass
confirmationThe confirmation waiting for approval
deviationDeviation report: step position, expected element, a summary of the current screen and similar elements
deviceThe device, written as env:<environment ID>
failedThe first failed step
inspectCompact snapshot at the end
messageWhy it did not pass
pauseWhere it paused for a confirmation (path and sub); pass it when resuming
resumeStep to resume from
runIdRun ID
statuspassed, failed, deviated, paused, cancelled or limited
stepsPer-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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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:

FieldDescription
appsInstalled apps: package names and readable names
deviceThe device, written as env:<environment ID>
note
outputThe raw output when listing on the device instead, one package:name per line
sourceWhere 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.

ParameterTypeRequiredDescription
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
packagestringYesApp package name

Returns: The result of the app operation.

FieldDescription
channelExecution channel
deviceThe device, written as env:<environment ID>
durationMs
exitCodeExit code
invokeId
outputBytes
statussucceeded, failed or timed_out
stderrDevice error output
stderrTruncated
stdoutDevice 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.

ParameterTypeRequiredDescription
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
packagestringYesApp package name

Returns: The result of the app operation.

FieldDescription
channelExecution channel
deviceThe device, written as env:<environment ID>
durationMs
exitCodeExit code
invokeId
outputBytes
statussucceeded, failed or timed_out
stderrDevice error output
stderrTruncated
stdoutDevice 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.

ParameterTypeRequiredDescription
app_idsinteger[]required in the remote formApp IDs in the app library
devicestringrequired in the remote formremote: 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
pathstringNoPath of an installer on this computer; only in the stdio local form; only in the stdio form

Returns: The result of the app install.

FieldDescription
deviceThe device, written as env:<environment ID>
hint
itemsStdio local form: the install result for each app
okStdio local form: whether the desktop app has finished
statusTask status
taskPlatform task ID; check its progress and result with job_get
taskIdStdio 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.

ParameterTypeRequiredDescription
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
keep_databooleanNoKeep the app's data
packagestringYesApp package name

Returns: The result of the app operation.

FieldDescription
channelExecution channel
deviceThe device, written as env:<environment ID>
durationMs
exitCodeExit code
invokeId
outputBytes
statussucceeded, failed or timed_out
stderrDevice error output
stderrTruncated
stdoutDevice 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.

ParameterTypeRequiredDescription
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
packagestringYesApp package name

Returns: The result of the app operation.

FieldDescription
channelExecution channel
deviceThe device, written as env:<environment ID>
durationMs
exitCodeExit code
invokeId
outputBytes
statussucceeded, failed or timed_out
stderrDevice error output
stderrTruncated
stdoutDevice 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.

ParameterTypeRequiredDescription
content_base64stringYesFile content in base64; only in the remote form
devicestringrequired in the remote formremote: 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
namestringrequired in the remote formremote: File name; stdio: File name on the device (in the download folder); defaults to the local file name
local_pathstringYesPath of the file on this computer; only in the stdio form

Returns: The result of the file push.

FieldDescription
deviceThe device, written as env:<environment ID>
hint
okStdio local form: whether the desktop app has finished
statusTask status
taskPlatform task ID; check its progress and result with job_get
taskIdStdio 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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
pathstringYesPath of the file on the device
local_pathstringNoWhere 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.

FieldDescription
deviceThe device, written as env:<environment ID>
hint
okStdio local form: whether the desktop app has finished
statusTask status
taskPlatform task ID; check its progress and result with job_get
taskIdStdio 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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.

FieldDescription
deviceThe device, written as env:<environment ID>
opstart, stop, reboot, pause, resume or sync
resultThe raw result returned by the platform or the desktop app
statusTask status
taskPlatform 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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.

FieldDescription
deviceThe device, written as env:<environment ID>
opstart, stop, reboot, pause, resume or sync
resultThe raw result returned by the platform or the desktop app
statusTask status
taskPlatform 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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.

FieldDescription
deviceThe device, written as env:<environment ID>
opstart, stop, reboot, pause, resume or sync
resultThe raw result returned by the platform or the desktop app
statusTask status
taskPlatform 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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.

FieldDescription
deviceThe device, written as env:<environment ID>
opstart, stop, reboot, pause, resume or sync
resultThe raw result returned by the platform or the desktop app
statusTask status
taskPlatform 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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.

FieldDescription
deviceThe device, written as env:<environment ID>
opstart, stop, reboot, pause, resume or sync
resultThe raw result returned by the platform or the desktop app
statusTask status
taskPlatform 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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
stopbooleanNoIf it is running or paused, shut it down first and then sync

Returns: The result of the environment lifecycle operation.

FieldDescription
deviceThe device, written as env:<environment ID>
opstart, stop, reboot, pause, resume or sync
resultThe raw result returned by the platform or the desktop app
statusTask status
taskPlatform 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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:

FieldDescription
backups
deviceThe 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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
namestringNoName of the full backup
packagestringNoApp package name: make an app backup of this app only

Returns: Backup record.

FieldDescription
appPackagePackage name of an app backup
createdAtCreation time
deviceThe device, written as env:<environment ID>
envId
idBackup ID
kindfull is a full backup; app-sandbox is an app backup
name
purposesync 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.

ParameterTypeRequiredDescription
backup_idintegerYesBackup ID
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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_versionbooleanNoSkip the version check for app restores
intentstringNoWhat 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.

FieldDescription
deviceThe device, written as env:<environment ID>
hint
pendingFull backups: the backup to restore at the next start
status
taskPlatform task ID; check its progress and result with job_get
taskIdTask 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.

ParameterTypeRequiredDescription
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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_hoursintegerNoHours it stays valid (default 24)
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
max_downloadsintegerNoMaximum number of downloads (default 5)
package_idstringYesPackage ID

Returns: Share link.

FieldDescription
deviceThe device, written as env:<environment ID>
expiresAtExpiry time
shareId
shareUrlShare 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.

ParameterTypeRequiredDescription
taskstringYesremote: Task ID; stdio: Task ID: platform tasks are numbers, local flow tasks start with job_

Returns: The task's status and result.

FieldDescription
IDPlatform task ID
deviceThe device, written as env:<environment ID>
expiresInHow many seconds the download link stays valid
jobLocal flow task ID
message
percent
resultTask result; for flows, the run report
size
stage
statusTask status
typeTask type
urlThe 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.

ParameterTypeRequiredDescription
atstringNoPosition of the paused step, from pause.path in the previous result
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
flowobjectrequired in the remote formremote: Flow content (schema yunyoo.flow/2); stdio: Flow content (schema yunyoo.flow/2); give either this or file
fromintegerNoStep to start from (from 1), used when resuming after a confirmation or a deviation
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
subintegerNoWhich controlled action within the paused step, from pause.sub in the previous result
varsobjectNoremote: 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
filestringNoFlow 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.

ParameterTypeRequiredDescription
runstringYesRun 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.

ParameterTypeRequiredDescription
devicestringNoTarget device: env:<environment ID> or an environment ID; without run, only the latest run on this device
runstringNoRun 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.

ParameterTypeRequiredDescription
confirmation_idstringYesConfirmation ID
wait_msintegerNoMaximum wait in milliseconds, 0–60000, default 30000

Returns: The confirmation's status.

FieldDescription
action
categoriesRisk categories
createdAtCreation time
decidedAtWhen it was decided
envId
executedAtWhen it ran
expiresAtExpiry time
idConfirmation ID
intent
statuspending, approved, denied, expired, cancelled or executed
summaryAction summary
urlConfirmation 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.

ParameterTypeRequiredDescription
confirmation_idstringYesConfirmation 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.

ParameterTypeRequiredDescription
devicestringrequired in the remote formremote: 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
reasonstringNoWhy 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.

ParameterTypeRequiredDescription
argvstring[]YesCommand and arguments (argv)
confirmation_idstringNoID 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
devicestringrequired in the remote formremote: 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
intentstringNoWhat this step is for, recorded in the confirmation and the run record; it can only add risk categories, never remove them
shellbooleanNoRun through the shell
timeout_msintegerNoRun 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.

ParameterTypeRequiredDescription
devicestringNoTarget 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.

ParameterTypeRequiredDescription
devicestringNoTarget device: env:<environment ID> or an environment ID; defaults to the device picked with device_use or the --device/--env startup option
opstringYesstart, stop, reboot, pause or resume

Returns: The result of the environment lifecycle operation.

FieldDescription
deviceThe device, written as env:<environment ID>
opstart, stop, reboot, pause, resume or sync
resultThe raw result returned by the platform or the desktop app
statusTask status
taskPlatform task ID; check its progress and result with job_get