yunyoo

Documentation

Command-line reference

Last updated:Nov 13, 2026

This page lists every command and option of the yunyoo command line. It is exported from the command line itself and matches what yunyoo <command> --help prints. For installation, sign-in and common usage, see Command-line tool.

Global options

Global options can go before or after the command, for example yunyoo --format json env list.

OptionDescription
--profile <PROFILE>The configuration profile to use (dev, prod and so on)
--endpoint <ENDPOINT>Platform endpoint (overrides the profile and the default); only the platform's own addresses and loopback addresses are accepted
--format <FORMAT>Output format; values: human, json; default human
--env <ENV>Run this command on the given environment (numeric ID; overrides the current selection for this command only, without changing the saved selection)
--debugDebug: print each platform request's signature headers to stderr (without credentials)
--localRun through the desktop app's local API on this computer (reads cli-auth.json and does not use the cloud credential)
--local-auth <FILE>Local API credential file (defaults to cli-auth.json in $CPD_DATA_ROOT or the desktop app's data folder)
--device <DEVICE>Target device: env:<environment ID> or an environment ID (--env <ID> is the same as env:<ID>)
--run <ID>Run ID: this command's automation calls are recorded under this run (defaults to the YUNYOO_RUN environment variable)
--skill <NAME>Run with a Skill's delegated token (defaults to the YUNYOO_SKILL environment variable); it only works on the device and apps bound when it was issued
--no-waitWhen an action needs a person's confirmation, return right away with exit code 3 instead of waiting for approval

auth

Sign-in and local credentials.

auth login

Sign in with a machine token (--token, or read from standard input)

OptionDescription
--token <TOKEN>Machine token; read from standard input when omitted

auth logout

Sign out: clear the local credential.

auth whoami

Show the user and scopes of the current credential.

env

List, select, start, stop, pause and sync environments.

env list

List your cloud phones (within the credential's range)

env use

Select the current environment (saved locally)

OptionDescription
<ID>Required; Environment ID

env current

Show the currently selected environment.

env start

Start.

OptionDescription
<ENV>Environment ID; defaults to --env or --device, and to the selected environment when neither is given

env stop

Shut down.

OptionDescription
<ENV>Environment ID; defaults to --env or --device, and to the selected environment when neither is given

env reboot

Reboot.

OptionDescription
<ENV>Environment ID; defaults to --env or --device, and to the selected environment when neither is given

env pause

Pause a running environment on a local node.

OptionDescription
<ENV>Environment ID; defaults to --env or --device, and to the selected environment when neither is given

env resume

Resume a paused environment.

OptionDescription
<ENV>Environment ID; defaults to --env or --device, and to the selected environment when neither is given

env sync

Sync a local environment's data to the cloud.

OptionDescription
<ENV>Environment ID; defaults to --env or --device, and to the selected environment when neither is given
--stopIf it is running or paused, shut it down first and then sync (without it, the platform returns 5345)
--waitWait for this sync to finish

devices

List the devices you can operate (environment records, with their node and sync state)

OptionDescription
--kind <KIND>List only one kind: env

tasks

Desktop app scheduled tasks (only with --local)

tasks list

List scheduled tasks.

tasks get

Show a task.

OptionDescription
<ID>Required; Scheduled task ID

tasks run

Run now (the target device comes from --device; by default, from the task's binding and auto-discovery)

OptionDescription
<ID>Required; Scheduled task ID

tasks runs

Runs.

OptionDescription
<ID>Required; Scheduled task ID
--limit <LIMIT>Maximum number of entries to show; default 20

node

Nodes (read-only summary)

node status

Your own nodes and the cloud nodes your environments run on: type, online state, slots and health check.

OptionDescription
--provider <PROVIDER>Only show the given node (providerId in the output)

observe

Observe (UI tree, screenshots, status)

observe inspect

Read the screen: a compact snapshot with one element per line; --format json prints a structured tree.

OptionDescription
--allInclude off-screen and invisible elements
--scope <SCOPE>interactive (default, only elements that can be interacted with or have text) or all (list every element)
--under <UNDER>Only list the subtree under this element ID
--max <MAX>Maximum number of elements to list, 1–2000, default 150

observe find

Find elements on the current screen by text, regex, resource ID, description or class name, and suggest selectors that are unique on the current screen.

OptionDescription
--text <TEXT>Text contains this, case-insensitive
--regex <REGEX>Regex matched against the text or description
--id <ID>Resource ID; the package name can be left out
--desc <DESC>Description contains this, case-insensitive
--class <CLASS>Class name; the package name can be left out
--max <MAX>Maximum number of matches to return, 1–100, default 20
--allAlso search off-screen and invisible elements

observe screenshot

Take a screenshot (written to screenshot.png by default, or use --out -)

OptionDescription
--out <OUT>Where to save the screenshot; use - to write to standard output; default screenshot.png
--max-edge <MAX_EDGE>Long edge in pixels, 256–2048; when any of the size, format, quality or annotation options is given, the image is processed with them
--image-format <IMAGE_FORMAT>Image format: jpeg or png; defaults to the extension of --out; values: jpeg, png
--quality <QUALITY>JPEG quality, 1–100, default 75
--annotateMark the element IDs from the latest screen read on the image

observe status

Automation readiness and capabilities.

ui

UI control (tap, swipe, type, key, wait). When an action does not succeed, its result is still printed and the exit code is 3.

ui tap

Tap (by element first, coordinates when no element is available)

OptionDescription
--element <ELEMENT>Element ID within the snapshot
--snapshot <SNAPSHOT>Snapshot version the element belongs to (use with --element; taken from the first line of observe inspect)
--resource-id <RESOURCE_ID>resource-id selector
--text <TEXT>Text selector
--desc <DESC>Description (content-desc) selector
--at <AT>Normalized coordinates x,y (0..1), used when no element is available
--long-press-ms <LONG_PRESS_MS>Long-press duration in milliseconds
--verifyCheck whether the action took effect (whether the screen changed)

ui swipe

Swipe (normalized coordinates x,y)

OptionDescription
--from <FROM>Required; Start point x,y (0..1)
--to <TO>Required; End point x,y (0..1)
--duration-ms <DURATION_MS>Swipe duration in milliseconds; default 300
--verifyCheck whether the action took effect (whether the screen changed)

ui type

Type text into the focused field (or the one given by --element)

OptionDescription
<TEXT>Required; The text to type
--clearClear before typing
--submitPress Enter after typing (to submit a search or a form)
--verifyCheck whether the action took effect (whether the screen changed)
--element <ELEMENT>Target element (defaults to the focused one)
--snapshot <SNAPSHOT>Snapshot version the element belongs to (use with --element; taken from the first line of observe inspect)

ui key

Send a key (Android key code, such as 66 for Enter or 4 for Back)

OptionDescription
<CODE>Required; Android key code
--verifyCheck whether the action took effect (whether the screen changed)

ui wait

Wait for a condition: an element appears (default), --gone for it 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.

OptionDescription
--element <ELEMENT>Element ID within the snapshot
--snapshot <SNAPSHOT>Snapshot version the element belongs to (use with --element; taken from the first line of observe inspect)
--resource-id <RESOURCE_ID>resource-id selector
--text <TEXT>Text selector
--desc <DESC>Description (content-desc) selector
--at <AT>Normalized coordinates x,y (0..1), used when no element is available
--timeout-ms <TIMEOUT_MS>Wait limit in milliseconds (30000 at most); default 5000
--goneWait for the element given by the selector to disappear
--idle-ms <IDLE_MS>Wait until the screen stays unchanged for this many milliseconds
--animationWait for animations to end
--package <PACKAGE>Wait for this app to come to the foreground
--activity <ACTIVITY>Use with --package: wait for this activity to be in the foreground

ui editor

Trigger an editor action (such as Search or Go)

OptionDescription
<ACTION>Required; Input method action number, such as 2 Go, 3 Search, 4 Send or 6 Done

ui clear

Clear the focused input field.

ui batch

Submit several UI and app actions at once and run them step by step (same step structure as flows, up to 50 steps and 60 seconds)

OptionDescription
<FILE>Required; Steps file (.json or .yaml): an array of steps, or an object with steps
-e, --var <NAME=VALUE>A variable, written as NAME=value; repeatable. Takes precedence over the environment variable YUNYOO_VAR_NAME and the defaults in the file
--keep-goingKeep running the later steps after a step fails or deviates
--inspect-at-endAttach a compact snapshot at the end
--from <FROM>Step to start from (from 1), for resuming after a deviation or a confirmation
--confirmation <CONFIRMATION>ID of an approved confirmation; use with --from to resume

app

Apps (list, install, launch, stop, clear, uninstall)

app list

List the apps installed on the device.

app install

Install from the app library (or, with --local, install an APK from this computer with --apk)

OptionDescription
<IDS>...App library entry IDs (one or more)
--apk <APK>APK, XAPK or APKS file on this computer (only with --local, for environments on local nodes)

app launch

Launch an app.

OptionDescription
<PACKAGE>Required; App package name
--activity <ACTIVITY>The activity to launch; defaults to the app's launch activity

app stop

Stop an app.

OptionDescription
<PACKAGE>Required; App package name

app clear

Clear app data.

OptionDescription
<PACKAGE>Required; App package name

app update

Update the app to the current version in the app library.

OptionDescription
<PACKAGE>Required; App package name

app uninstall

Uninstall an app.

OptionDescription
<PACKAGE>Required; App package name
--keep-dataKeep the app's data

file

Files (pull)

file pull

Pull a file from the device (an async task in the cloud; with --local it is saved to --out right away)

OptionDescription
<PATH>Required; Path of the file on the device
--out <OUT>Where to save it on this computer (only with --local; defaults to a file of the same name in the current folder)

file push

Push a file from this computer to the device (to /sdcard/Download/ by default)

OptionDescription
<LOCAL>Required; Path of the file on this computer
<REMOTE>Target path or folder on the device

backup

Backups and portable packages (list, create, restore, package and export, download, import, share)

backup list

List the current environment's backups.

backup create

Create a backup of the environment; --app backs up only that app's data.

OptionDescription
<ENV>Environment ID; defaults to --env or --device, and to the selected environment when neither is given
--app <APP>App package name: make an app backup of this app only
--name <NAME>Backup name
--waitWait for the backup to finish

backup restore

Restore from one of the current environment's backups: a full backup is restored at the next start, and an app backup restores that app right away.

OptionDescription
<BACKUP_ID>Required; Backup ID
--account-password <ACCOUNT_PASSWORD>Account password (the platform checks it when the backup's device identity differs from the environment's current one; read from WP_ACCOUNT_PASSWORD by default)
--ignore-versionSkip the version check for app restores
--waitWait for an app restore task to finish

backup export

Package a backup as a .wp file and download it to this computer.

OptionDescription
<BACKUP_ID>Required; Backup ID
--out <OUT>Output file (defaults to the platform's file name)
--no-seedLeave the identity seed out of the package
--no-secure-stateLeave the secure state out of the package
--account-password <ACCOUNT_PASSWORD>Account password (the platform checks it when the seed is included; read from WP_ACCOUNT_PASSWORD by default)

backup share

Create a share link for a package (claiming always requires signing in)

OptionDescription
<PACKAGE_ID>Required; Package ID
--expires-hours <EXPIRES_HOURS>Hours it stays valid; default 24
--max-downloads <MAX_DOWNLOADS>Maximum number of downloads; default 5
--identity-transferAllow the recipient to take over the device identity in the package after importing (required for packages that contain a seed)

backup package

Package a backup as a .wp file (sealed by the platform, no passphrase needed; if the platform has not turned on sealed export yet, the older format reads the passphrase from WP_PASSPHRASE or standard input)

OptionDescription
<BACKUP_ID>Required; Backup ID
--no-seedLeave the identity seed out of the package (data packages include it by default, which requires re-entering your account password)
--no-secure-stateLeave the secure state out of the package (full packages include it by default; without it, the package cannot be used to create a new environment)
--account-password <ACCOUNT_PASSWORD>Account password (the platform checks it when the seed is included; read from WP_ACCOUNT_PASSWORD by default)
--waitWait for packaging to finish and print the package details

backup pull

Download a package to this computer.

OptionDescription
<PACKAGE_ID>Required; Package ID
--out <OUT>Output file (defaults to the platform's file name)

backup push

Upload a local .wp file; the platform checks it and imports it into the target environment (for older passphrase packages the passphrase is read from WP_PASSPHRASE or standard input, and wrap_key is derived on this computer only)

Alias: import

OptionDescription
<FILE>Required; .wp file
--mode <MODE>Import mode: restore | data-env | app | profile; default restore
--name <NAME>Data environment name for the data-env mode
--new-envCreate a new environment from an environment package (no --env needed; --sku is required)
--sku <SKU>SKU ID for the new environment (must match the package's device model and root variant)
--proxy <PROXY>Proxy ID to bind to the new environment
--attestation <ATTESTATION>Attestation source for the new environment: pool or user:<keyboxId>
--title <TITLE>Name of the new environment
--egress-confirm <EGRESS_CONFIRM>Egress confirmation token returned by the check (used when the proxy and the package's anchor need confirming)
--dry-runOnly run the check: print the plan without creating an import task
--identity-transferConfirm moving the device identity in the package to the target environment (required when an automated import takes over the identity in the package)
--bind-ackConfirm the import when the target environment has a bound app but the package's source did not (third-party apps other than the bound app will be disabled)
--waitWait for the import task to finish

run

Run-command escape hatch (must be granted explicitly)

OptionDescription
--shellRun with shell semantics (the whole string as a single argument)
--asyncRun asynchronously (returns a task ID)
--timeout-ms <TIMEOUT_MS>Timeout in milliseconds
<ARGV>...Required; Command and arguments (argv; put them after --)

connect

Controlled local bridge escape hatch (must be granted explicitly); opens a local port for debugging tools on this computer.

OptionDescription
--port <PORT>Local listening port; default 15555

batch

Batch: run the same action on several devices picked by a selector.

OptionDescription
--group <GROUP>Selector: group ID
--tag <TAG>Selector: tag ID
--envs <ENVS>Selector: an explicit set of environment IDs; repeatable

batch run

Run the command on each device.

OptionDescription
--shellRun with shell semantics (the whole string as a single argument)
--asyncRun asynchronously (returns a task ID)
--timeout-ms <TIMEOUT_MS>Timeout in milliseconds
<ARGV>...Required; Command and arguments (argv; put them after --)

batch launch

Launch the app on each device.

OptionDescription
<PACKAGE>Required; App package name

batch stop

Stop the app on each device.

OptionDescription
<PACKAGE>Required; App package name

batch ui

Run the UI action on each device.

batch ui tap

Tap (on multiple devices, locate by text, resource ID, description or coordinates only)

OptionDescription
--element <ELEMENT>Element ID within the snapshot
--snapshot <SNAPSHOT>Snapshot version the element belongs to (use with --element; taken from the first line of observe inspect)
--resource-id <RESOURCE_ID>resource-id selector
--text <TEXT>Text selector
--desc <DESC>Description (content-desc) selector
--at <AT>Normalized coordinates x,y (0..1), used when no element is available
--long-press-ms <LONG_PRESS_MS>Long-press duration in milliseconds

batch ui type

Type text into the focused field.

OptionDescription
<TEXT>Required; The text to type
--clearClear before typing
--submitPress Enter after typing

batch ui key

Send a key (Android key code)

OptionDescription
<CODE>Required; Android key code

batch ui swipe

Swipe (normalized coordinates x,y)

OptionDescription
--from <FROM>Required; Start point x,y (0..1)
--to <TO>Required; End point x,y (0..1)
--duration-ms <DURATION_MS>Swipe duration in milliseconds; default 300

macro

Macro recording and replay.

macro check

Check a macro file's format and list the variables and secret placeholders to pass at run time.

OptionDescription
<FILE>Required; Macro file (.json or .yaml)
-e, --var <NAME=VALUE>A variable, written as NAME=value; repeatable

macro run

Run a macro; version 1.0 macros replay as before.

OptionDescription
<FILE>Required; Macro file (.json or .yaml)
-e, --var <NAME=VALUE>A variable, written as NAME=value; repeatable. Takes precedence over the environment variable YUNYOO_VAR_NAME and the defaults in the file
--from <FROM>Step to start from (from 1), for resuming after a deviation or a confirmation
--confirmation <CONFIRMATION>ID of an approved confirmation; use with --from to resume

macro save

Generate a macro draft from a run record.

OptionDescription
--run <RUN>Required; Run ID; see report show
-o, --output <OUTPUT>File to write (.json or .yaml); prints to the screen when omitted

macro migrate

Convert a version 1.0 macro to 2.0.

OptionDescription
<FILE>Required; Version 1.0 macro file
-o, --output <OUTPUT>File to write (.json or .yaml); prints to the screen when omitted

macro new

Generate a 2.0 macro template (.json or .yaml)

OptionDescription
<FILE>Required; The macro file to generate; the extension decides the format

job

Platform async tasks (power, backups, file transfers, app installs, flows)

job get

Get a task's status and result: platform tasks are numbers, local flow tasks start with job_.

OptionDescription
<ID>Required; Task ID

report

Run report.

report show

Show a run's report; without a run ID it uses the latest run, and --device only looks at that device.

OptionDescription
<RUN>Run ID

confirm

Confirmations: wait for a decision, withdraw or show one; only a person can approve, in the web or desktop app.

confirm wait

Wait for a confirmation's decision (up to 60 seconds per call)

OptionDescription
<ID>Required; Confirmation ID
--wait-ms <WAIT_MS>Maximum wait in milliseconds, 0–60000; default 30000

confirm cancel

Withdraw a confirmation that is still pending.

OptionDescription
<ID>Required; Confirmation ID

confirm show

Show a confirmation's current status.

OptionDescription
<ID>Required; Confirmation ID

handoff

Ask the user to take over the device (for payment, sign-in, a CAPTCHA or any screen the person has to handle themselves); without --reason, only the current state is shown.

OptionDescription
--reason <REASON>Why the user is needed

config

Configuration (endpoint, profile)

config show

Show the effective configuration.

config set-profile

Set the default profile.

OptionDescription
<NAME>Required; Profile name

config set-endpoint

Set the endpoint of a profile.

OptionDescription
<PROFILE>Required; Profile name
<ENDPOINT>Required; Platform endpoint URL

completions

Generate a shell completion script.

OptionDescription
<SHELL>Required; Shell type; values: bash, elvish, fish, powershell, zsh

mcp

Run as an MCP server (stdio, for AI agents to connect)

OptionDescription
--tools <GROUPS>Only offer tools from these groups (comma-separated); defaults to every allowed group; values: core, apps, files, lifecycle, backups, macros, escape; repeatable