命令行工具
最近更新:2026/11/13
yunyoo 命令行让你在终端或脚本里操作云手机:读取屏幕、点按和输入、管理应用和文件、开关机、做备份,也能把多步操作写成流程宏反复运行。它还能作为 MCP 服务运行,让 AI 助手接入,见 MCP。
命令行有两种用法:
- 云端:用机器 token 登录,经平台操作你名下的云手机,云端节点和本地节点上的都可以;
- 本机:加
--local,经这台电脑上的桌面端操作,不需要 token,见本地 API 与桌面任务。
安装
在下载页的「命令行工具(yunyoo CLI)」分组下载,下载前要输入下载密码。每个文件都附有 SHA-256,可以先核对再安装。
| 系统 | 安装包 | 安装方法 |
|---|---|---|
| macOS(Apple 芯片与 Intel) | pkg | 双击打开,按提示安装,命令装在 /usr/local/bin/yunyoo;安装包有开发者签名并通过了 Apple 的公证,系统不会提示来源不明 |
| macOS | tar.gz | 解压后把 yunyoo 放进 PATH 里的目录 |
| Linux(x86_64、ARM64) | deb | sudo apt install ./<下载的文件名>.deb |
| Linux | tar.gz | 解压后把 yunyoo 放进 PATH 里的目录 |
| Windows(x86_64) | zip | 解压后把 yunyoo.exe 所在目录加入 PATH;安装包没有签名,首次运行时系统可能提示来源未知 |
装好后确认版本:
yunyoo --version
旧命令名 wp_cli 仍可使用,效果相同,每天会提示一次改用 yunyoo;设置环境变量 YUNYOO_SILENCE_DEPRECATION=1 可以关掉提示。这个旧名以后会停用,脚本里请改用 yunyoo。
登录
先在网页端或桌面端的「账户设置 → 自动化」签发一枚机器 token,选好它能做的操作和能碰的云手机,见自动化概览。然后登录:
printf '%s' "$YUNYOO_TOKEN" | yunyoo auth login
yunyoo auth whoami
auth login 不带 --token 时从标准输入读取,token 不会留在命令历史里。凭据保存在系统钥匙串里,钥匙串不可用时保存在只有你能读的文件里。yunyoo auth logout 清除本机凭据。
命令行只把登录凭据发给云柚平台和这台电脑自己。平台地址被改成别的网址时(比如用 --endpoint),命令直接报错,不发出任何请求。
选中云手机
yunyoo env list
yunyoo env use 123
yunyoo env current
选中后,后面的命令都作用在这台云手机上。只想让某一条命令作用在别的云手机上,加 --env:
yunyoo observe screenshot --env 456 --out other.png
常用操作
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 inspect一行列出一个界面元素,第一行给出前台应用和快照版本;点按时优先按文字、描述或资源 ID 找元素,找不到可用元素时才用坐标(--at 0.5,0.8,取值 0 到 1)。ui key发送 Android 按键码,如 4 是返回键、66 是回车。ui type可靠支持英文与数字等 ASCII 文本;能不能输入中文取决于设备,不支持时会报错并说明原因。ui wait一次最长等 30 秒,到时还没等到就返回等待超时(1003);需要等更久就再执行一次。env start、env stop发出请求后就返回:开机要几分钟,关机也要等一会儿。接着要做依赖开关机状态的操作(比如还原整机备份)时,先用yunyoo env list确认状态已经变了。- 执行命令(
run)和把设备端口桥接到本机(connect)默认不授予,签发 token 时要单独勾选。
全部命令和参数见命令行参考。
输出与退出码
给脚本用时加 --format json,结果按 JSON 输出,出错时在标准错误输出写一个 error 对象:
yunyoo --format json env list
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 2 | 用法或参数有误、没有登录、没有选中云手机、token 缺少所需的作用域 |
| 3 | 目标上的问题:云手机不存在或不可用、操作失败、流程偏离、需要人工确认或被拒绝 |
| 4 | 系统问题:连不上平台、平台返回错误、凭据读写失败等 |
点按、输入、等待这类动作没做成时(比如找不到元素、等待超时),结果照常输出:里面的 ok 为 false,error_code 说明原因,含义见自动化概览;退出码为 3,脚本可以直接用它判断这一步成没成。1.5.1 及更早的版本这种情况退出码是 0,只能看结果里的 ok。
一次执行多步:批量与流程宏
把多步操作写进一个文件,一次提交,由平台逐步执行:
yunyoo ui batch steps.yaml
要反复运行的流程写成流程宏。macro new 生成一个模板,macro check 检查格式并列出运行时要提供的变量,macro run 运行:
yunyoo macro new search.yaml
yunyoo macro check search.yaml
yunyoo macro run search.yaml -e KEYWORD=case
schema: yunyoo.flow/2
name: 打开应用并搜索
appId: com.example.app
env:
KEYWORD: phone case
steps:
- launchApp
- tapOn: { desc: Search }
label: 打开搜索
- inputText: { text: "${KEYWORD}", submit: true }
- waitUntil: { visible: { textContains: "${KEYWORD}" } }
timeout: 15000
- takeScreenshot: result
执行时找不到要操作的元素,或界面和宏里写的预期对不上,流程就停下,退出码为 3,并告诉你停在第几步、要找的元素和当时的界面;改好宏文件后,用 --from <步号> 从那一步续跑。变量可以用 -e NAME=值 或环境变量 YUNYOO_VAR_NAME 提供;密码一类的值写成密码占位,运行时从环境变量 YUNYOO_SECRET_NAME 或系统钥匙串读取,不会写进运行记录。
yunyoo report show 查看最近一次运行的每一步;yunyoo macro save --run <运行编号> 可以把一次成功的运行整理成宏草稿。
需要确认的操作
清除应用数据、卸载应用、执行命令,以及涉及付款、消息、账号等的高风险操作,可能需要你本人批准。遇到这类操作时命令行会停下,给出确认页的链接并等待;你在网页端或桌面端(1.1.0 起)的「自动化 → 确认与报告」里批准后,命令行自动继续,拒绝则以退出码 3 结束。加 --no-wait 时不等待,直接以退出码 3 返回,稍后可以用 confirm wait 查看结果。
如果有人在查看器里接管了这台云手机,自动化的操作会被拒绝,直到在查看器顶部点「交还」。
本机模式
桌面端开着并已登录时,加 --local 改经桌面端执行,不需要 token:
yunyoo --local devices
yunyoo --local --device env:123 observe screenshot --out a.png
本机模式能操作这台电脑上本地节点里的环境,也能经桌面端操作云端节点上的环境。桌面端的本地 API 要处于开启状态,见本地 API 与桌面任务。
作为 MCP 服务运行
yunyoo mcp
以标准输入输出提供 MCP 工具,供同一台电脑上的 AI 助手接入;加 --local 则经桌面端执行。各助手的配置写法见 MCP。
更新与卸载
- 更新:从下载页下载新版本,按同样的方式安装,会覆盖旧版本。
- 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。 - 解压安装的:删掉
yunyoo(Windows 为yunyoo.exe和wp_cli.exe)即可。
卸载不会删除平台上的 token;不再使用时,在「账户设置 → 自动化」里吊销它。
