云柚

文档中心

命令行工具

最近更新:2026/11/13

yunyoo 命令行让你在终端或脚本里操作云手机:读取屏幕、点按和输入、管理应用和文件、开关机、做备份,也能把多步操作写成流程宏反复运行。它还能作为 MCP 服务运行,让 AI 助手接入,见 MCP。

命令行有两种用法:

  • 云端:用机器 token 登录,经平台操作你名下的云手机,云端节点和本地节点上的都可以;
  • 本机:加 --local,经这台电脑上的桌面端操作,不需要 token,见本地 API 与桌面任务。

安装

在下载页的「命令行工具(yunyoo CLI)」分组下载,下载前要输入下载密码。每个文件都附有 SHA-256,可以先核对再安装。

系统安装包安装方法
macOS(Apple 芯片与 Intel)pkg双击打开,按提示安装,命令装在 /usr/local/bin/yunyoo;安装包有开发者签名并通过了 Apple 的公证,系统不会提示来源不明
macOStar.gz解压后把 yunyoo 放进 PATH 里的目录
Linux(x86_64、ARM64)debsudo apt install ./<下载的文件名>.deb
Linuxtar.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;不再使用时,在「账户设置 → 自动化」里吊销它。