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.
| Option | Description |
|---|---|
--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) |
--debug | Debug: print each platform request's signature headers to stderr (without credentials) |
--local | Run 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-wait | When 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)
| Option | Description |
|---|---|
--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)
| Option | Description |
|---|---|
<ID> | Required; Environment ID |
env current
Show the currently selected environment.
env start
Start.
| Option | Description |
|---|---|
<ENV> | Environment ID; defaults to --env or --device, and to the selected environment when neither is given |
env stop
Shut down.
| Option | Description |
|---|---|
<ENV> | Environment ID; defaults to --env or --device, and to the selected environment when neither is given |
env reboot
Reboot.
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
<ENV> | Environment ID; defaults to --env or --device, and to the selected environment when neither is given |
env resume
Resume a paused environment.
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
<ENV> | Environment ID; defaults to --env or --device, and to the selected environment when neither is given |
--stop | If it is running or paused, shut it down first and then sync (without it, the platform returns 5345) |
--wait | Wait for this sync to finish |
devices
List the devices you can operate (environment records, with their node and sync state)
| Option | Description |
|---|---|
--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.
| Option | Description |
|---|---|
<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)
| Option | Description |
|---|---|
<ID> | Required; Scheduled task ID |
tasks runs
Runs.
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
--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.
| Option | Description |
|---|---|
--all | Include 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.
| Option | Description |
|---|---|
--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 |
--all | Also search off-screen and invisible elements |
observe screenshot
Take a screenshot (written to screenshot.png by default, or use --out -)
| Option | Description |
|---|---|
--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 |
--annotate | Mark 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)
| Option | Description |
|---|---|
--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 |
--verify | Check whether the action took effect (whether the screen changed) |
ui swipe
Swipe (normalized coordinates x,y)
| Option | Description |
|---|---|
--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 |
--verify | Check whether the action took effect (whether the screen changed) |
ui type
Type text into the focused field (or the one given by --element)
| Option | Description |
|---|---|
<TEXT> | Required; The text to type |
--clear | Clear before typing |
--submit | Press Enter after typing (to submit a search or a form) |
--verify | Check 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)
| Option | Description |
|---|---|
<CODE> | Required; Android key code |
--verify | Check 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.
| Option | Description |
|---|---|
--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 |
--gone | Wait for the element given by the selector to disappear |
--idle-ms <IDLE_MS> | Wait until the screen stays unchanged for this many milliseconds |
--animation | Wait 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)
| Option | Description |
|---|---|
<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)
| Option | Description |
|---|---|
<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-going | Keep running the later steps after a step fails or deviates |
--inspect-at-end | Attach 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)
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
<PACKAGE> | Required; App package name |
--activity <ACTIVITY> | The activity to launch; defaults to the app's launch activity |
app stop
Stop an app.
| Option | Description |
|---|---|
<PACKAGE> | Required; App package name |
app clear
Clear app data.
| Option | Description |
|---|---|
<PACKAGE> | Required; App package name |
app update
Update the app to the current version in the app library.
| Option | Description |
|---|---|
<PACKAGE> | Required; App package name |
app uninstall
Uninstall an app.
| Option | Description |
|---|---|
<PACKAGE> | Required; App package name |
--keep-data | Keep 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)
| Option | Description |
|---|---|
<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)
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
<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 |
--wait | Wait 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.
| Option | Description |
|---|---|
<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-version | Skip the version check for app restores |
--wait | Wait for an app restore task to finish |
backup export
Package a backup as a .wp file and download it to this computer.
| Option | Description |
|---|---|
<BACKUP_ID> | Required; Backup ID |
--out <OUT> | Output file (defaults to the platform's file name) |
--no-seed | Leave the identity seed out of the package |
--no-secure-state | Leave 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)
| Option | Description |
|---|---|
<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-transfer | Allow 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)
| Option | Description |
|---|---|
<BACKUP_ID> | Required; Backup ID |
--no-seed | Leave the identity seed out of the package (data packages include it by default, which requires re-entering your account password) |
--no-secure-state | Leave 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) |
--wait | Wait for packaging to finish and print the package details |
backup pull
Download a package to this computer.
| Option | Description |
|---|---|
<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
| Option | Description |
|---|---|
<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-env | Create 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-run | Only run the check: print the plan without creating an import task |
--identity-transfer | Confirm moving the device identity in the package to the target environment (required when an automated import takes over the identity in the package) |
--bind-ack | Confirm 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) |
--wait | Wait for the import task to finish |
run
Run-command escape hatch (must be granted explicitly)
| Option | Description |
|---|---|
--shell | Run with shell semantics (the whole string as a single argument) |
--async | Run 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.
| Option | Description |
|---|---|
--port <PORT> | Local listening port; default 15555 |
batch
Batch: run the same action on several devices picked by a selector.
| Option | Description |
|---|---|
--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.
| Option | Description |
|---|---|
--shell | Run with shell semantics (the whole string as a single argument) |
--async | Run 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.
| Option | Description |
|---|---|
<PACKAGE> | Required; App package name |
batch stop
Stop the app on each device.
| Option | Description |
|---|---|
<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)
| Option | Description |
|---|---|
--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.
| Option | Description |
|---|---|
<TEXT> | Required; The text to type |
--clear | Clear before typing |
--submit | Press Enter after typing |
batch ui key
Send a key (Android key code)
| Option | Description |
|---|---|
<CODE> | Required; Android key code |
batch ui swipe
Swipe (normalized coordinates x,y)
| Option | Description |
|---|---|
--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.
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
--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.
| Option | Description |
|---|---|
<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)
| Option | Description |
|---|---|
<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_.
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
<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)
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
<ID> | Required; Confirmation ID |
confirm show
Show a confirmation's current status.
| Option | Description |
|---|---|
<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.
| Option | Description |
|---|---|
--reason <REASON> | Why the user is needed |
config
Configuration (endpoint, profile)
config show
Show the effective configuration.
config set-profile
Set the default profile.
| Option | Description |
|---|---|
<NAME> | Required; Profile name |
config set-endpoint
Set the endpoint of a profile.
| Option | Description |
|---|---|
<PROFILE> | Required; Profile name |
<ENDPOINT> | Required; Platform endpoint URL |
completions
Generate a shell completion script.
| Option | Description |
|---|---|
<SHELL> | Required; Shell type; values: bash, elvish, fish, powershell, zsh |
mcp
Run as an MCP server (stdio, for AI agents to connect)
| Option | Description |
|---|---|
--tools <GROUPS> | Only offer tools from these groups (comma-separated); defaults to every allowed group; values: core, apps, files, lifecycle, backups, macros, escape; repeatable |
