Command line
Last updated:Nov 13, 2026
The yunyoo command line lets you drive cloud phones from a terminal or a script: read the screen, tap and type, manage apps and files, power devices on and off, take backups, and save multi-step work as a flow macro you can run again. It can also run as an MCP server so an AI assistant can connect; see MCP.
There are two ways to use it:
- Cloud: sign in with a machine token and work on your cloud phones through the platform, whether they run on cloud nodes or local nodes;
- On this computer: add
--localto go through the desktop app on this computer, with no token; see Local API and desktop tasks.
Install
Download it from the "Command line (yunyoo CLI)" group on the download page. The page asks for the download password first. Every file lists its SHA-256 so you can check it before installing.
| System | Package | How to install |
|---|---|---|
| macOS (Apple silicon and Intel) | pkg | Open it and follow the installer; the command goes to /usr/local/bin/yunyoo. The package is signed with our Developer ID and notarized by Apple, so macOS opens it without an unidentified-developer warning |
| macOS | tar.gz | Unpack it and put yunyoo in a folder on your PATH |
| Linux (x86_64, ARM64) | deb | sudo apt install ./<downloaded file>.deb |
| Linux | tar.gz | Unpack it and put yunyoo in a folder on your PATH |
| Windows (x86_64) | zip | Unpack it and add the folder with yunyoo.exe to your PATH; the package is not signed, so Windows may warn that the publisher is unknown the first time you run it |
Then check the version:
yunyoo --version
The old name wp_cli still works and does the same thing, with a reminder once a day to switch to yunyoo; set YUNYOO_SILENCE_DEPRECATION=1 to turn the reminder off. The old name will go away later, so use yunyoo in your scripts.
Sign in
First issue a machine token under Account settings → Automation in the web console or the desktop app, and choose what it may do and which cloud phones it may touch; see Automation overview. Then sign in:
printf '%s' "$YUNYOO_TOKEN" | yunyoo auth login
yunyoo auth whoami
Without --token, auth login reads the token from standard input, so it stays out of your shell history. The credential is kept in the system keychain, or in a file only you can read when no keychain is available. yunyoo auth logout removes it from this computer.
The command line sends your sign-in credential only to yunyoo and to this computer itself. If the platform address is changed to any other site (with --endpoint, for example), the command stops with an error and sends nothing.
Pick a cloud phone
yunyoo env list
yunyoo env use 123
yunyoo env current
Once one is picked, later commands act on it. To point a single command at another cloud phone, add --env:
yunyoo observe screenshot --env 456 --out other.png
Everyday commands
yunyoo env start 123
yunyoo observe inspect
yunyoo observe screenshot --out home.png
yunyoo observe find --text Settings
yunyoo ui tap --text Settings
yunyoo ui type "hello" --submit
yunyoo ui wait --text Wi-Fi --timeout-ms 8000
yunyoo ui key 4
yunyoo app list
yunyoo app launch com.android.settings
yunyoo file push ./photo.jpg
yunyoo backup create --name before-update --wait
observe inspectlists one screen element per line, and the first line shows the app in front and the snapshot version. Taps look for an element by text, description or resource ID first, and fall back to a position (--at 0.5,0.8, from 0 to 1) only when no usable element is found.ui keysends an Android key code: 4 is Back and 66 is Enter.ui typereliably types ASCII text such as English letters and digits. Whether other languages can be typed depends on the device; when it can't, you get an error that says why.ui waitwaits 30 seconds at most. If the condition still isn't met, it returns a wait timeout (1003); run it again to wait longer.env startandenv stopreturn as soon as the request is sent: starting takes a few minutes, and stopping takes a moment too. Before a step that depends on the phone being on or off (restoring a full backup, for example), check withyunyoo env listthat the state has changed.- Running commands on the device (
run) and bridging a device port to this computer (connect) are off unless you tick them when you issue the token.
Every command and option is listed in the command-line reference.
Output and exit codes
For scripts, add --format json. Results come out as JSON, and errors are written to standard error as an error object:
yunyoo --format json env list
| Exit code | Meaning |
|---|---|
| 0 | Success |
| 2 | Wrong usage or arguments, not signed in, no cloud phone picked, or the token lacks a scope the command needs |
| 3 | A problem on the target: the cloud phone doesn't exist or isn't available, the action failed, a flow went off course, or a step needs approval or was declined |
| 4 | A system problem: the platform can't be reached, the platform returned an error, the credential can't be read or written, and so on |
When a tap, typing or a wait does not succeed (no matching element or a wait that timed out, for example), the result is still printed: its ok is false and error_code says why (see Automation overview for the meanings). The exit code is 3, so a script can tell from it whether the step worked. In 1.5.1 and earlier the exit code was 0 in this case, and only ok in the result showed it.
Several steps at once: batches and flow macros
Put several steps in one file and submit them together; the platform runs them in order:
yunyoo ui batch steps.yaml
Work you repeat goes into a flow macro. macro new writes a template, macro check checks the format and lists the values you need to pass in, and macro run runs it:
yunyoo macro new search.yaml
yunyoo macro check search.yaml
yunyoo macro run search.yaml -e KEYWORD=case
schema: yunyoo.flow/2
name: Open the app and search
appId: com.example.app
env:
KEYWORD: phone case
steps:
- launchApp
- tapOn: { desc: Search }
label: Open search
- inputText: { text: "${KEYWORD}", submit: true }
- waitUntil: { visible: { textContains: "${KEYWORD}" } }
timeout: 15000
- takeScreenshot: result
If a step can't find the element it should act on, or the screen doesn't match what the macro expects, the flow stops with exit code 3 and tells you the step, the element it was looking for and what was on screen. Fix the macro, then continue from that step with --from <step>. Pass values with -e NAME=value or the environment variable YUNYOO_VAR_NAME. Passwords and other secrets go in as secret placeholders; at run time they are read from YUNYOO_SECRET_NAME or the system keychain and never written to run records.
yunyoo report show lists every step of the latest run, and yunyoo macro save --run <run ID> turns a successful run into a draft macro.
Steps that need your approval
Clearing app data, uninstalling apps, running commands, and other high-risk steps such as payments, messages or account changes may need your approval. When one comes up, the command pauses, prints a link to the confirmation and waits. Approve it under Automation → Confirmations and reports in the web console or the desktop app (1.1.0 and later) and the command carries on; if you decline, it ends with exit code 3. With --no-wait it returns exit code 3 right away instead of waiting, and you can check the outcome later with confirm wait.
If someone has taken over the cloud phone in the viewer, automation actions are refused until they click Hand back at the top of the viewer.
On this computer
While the desktop app is open and signed in, add --local to go through it instead, with no token:
yunyoo --local devices
yunyoo --local --device env:123 observe screenshot --out a.png
This works on environments on this computer's local node, and on cloud-node environments through the desktop app. The desktop app's local API must be on; see Local API and desktop tasks.
Run as an MCP server
yunyoo mcp
This serves the MCP tools over standard input and output to AI assistants on the same computer; with --local it goes through the desktop app. For how to set up each assistant, see MCP.
Update and uninstall
- Update: download the new version and install it the same way; it replaces the old one.
- macOS (pkg):
sudo rm /usr/local/bin/yunyoo /usr/local/bin/wp_cli && sudo pkgutil --forget ai.yunyoo.cli. - Linux (deb):
sudo apt remove yunyoo-cli. - Unpacked copies: delete
yunyoo(on Windows,yunyoo.exeandwp_cli.exe).
Uninstalling doesn't remove the token on the platform; revoke it under Account settings → Automation when you no longer need it.
