云柚

文档中心

命令行参考

最近更新:2026/11/13

这里列出 yunyoo 命令行的全部命令与参数,内容由命令行自身导出,与 yunyoo <命令> --help 的说明一致。安装、登录与常见用法见命令行工具。

全局参数

全局参数写在命令之前或之后都可以,例如 yunyoo --format json env list。

参数说明
--profile <PROFILE>使用的配置 Profile(dev/prod 等)
--endpoint <ENDPOINT>平台端点(覆盖 profile 与默认);只接受本产品的平台地址与本机回环地址
--format <FORMAT>输出格式;取值:human、json;缺省 human
--env <ENV>本次命令作用于指定环境(数字 ID;单次覆盖当前选中,不改持久选中)
--debug调试:在 stderr 打印每个平台请求的请求签名头(不含凭据)
--local经本机桌面端本地 API 执行(读 cli-auth.json,不使用云端凭据)
--local-auth <FILE>本地 API 凭据文件(缺省为 $CPD_DATA_ROOT 或桌面端数据目录下的 cli-auth.json)
--device <DEVICE>目标设备:env:<环境 ID> 或环境 ID(--env <ID> 等价 env:<ID>)
--run <ID>运行编号:本次命令的自动化调用归入这次运行(缺省读环境变量 YUNYOO_RUN)
--skill <NAME>以某个 Skill 的委派令牌执行(缺省读环境变量 YUNYOO_SKILL);只能作用于签发时绑定的设备与应用
--no-wait遇到需要人工确认的操作时立即以退出码 3 返回,不等待批准

auth

登录与本地凭据。

auth login

登录:提供机器 token(--token,或从标准输入读取)

参数说明
--token <TOKEN>机器 token;不给时从标准输入读取

auth logout

登出:清除本地凭据。

auth whoami

显示当前凭据所属用户与作用域。

env

环境列表、选中、启停、暂停与同步。

env list

列出名下(且在凭据范围内)的云机。

env use

选中当前环境(写入本地状态)

参数说明
<ID>必填;环境标识

env current

显示当前选中环境。

env start

开机。

参数说明
<ENV>环境标识;缺省取 --env 或 --device,都没给时取当前选中环境

env stop

关机。

参数说明
<ENV>环境标识;缺省取 --env 或 --device,都没给时取当前选中环境

env reboot

重启。

参数说明
<ENV>环境标识;缺省取 --env 或 --device,都没给时取当前选中环境

env pause

暂停本地节点上运行中的环境。

参数说明
<ENV>环境标识;缺省取 --env 或 --device,都没给时取当前选中环境

env resume

继续已暂停的环境。

参数说明
<ENV>环境标识;缺省取 --env 或 --device,都没给时取当前选中环境

env sync

把本地环境的数据同步到云端。

参数说明
<ENV>环境标识;缺省取 --env 或 --device,都没给时取当前选中环境
--stop运行中或已暂停时先关机再同步(不加时平台返回 5345)
--wait等待这次同步结束

devices

列出可操作的设备(环境记录,带所在节点与同步状态)

参数说明
--kind <KIND>只列某一类:env

tasks

桌面端定时任务(仅 --local)

tasks list

列出定时任务。

tasks get

查看一个任务。

参数说明
<ID>必填;定时任务编号

tasks run

立即运行(目标设备取 --device,缺省按任务绑定与自动发现)

参数说明
<ID>必填;定时任务编号

tasks runs

运行记录。

参数说明
<ID>必填;定时任务编号
--limit <LIMIT>最多显示的条数;缺省 20

node

节点(只读摘要)

node status

自持节点与名下环境所在云端节点:类型、在线态、槽位与体检。

参数说明
--provider <PROVIDER>只看指定节点(输出中的 providerId)

observe

观测(UI 语义树 / 截图 / 状态)

observe inspect

读取界面:紧凑快照,一行一个元素;--format json 输出结构化树。

参数说明
--all含屏幕外与不可见的元素
--scope <SCOPE>interactive(缺省,只列可交互或带文字的元素)或 all(列出全部元素)
--under <UNDER>只列该编号元素下的子树
--max <MAX>最多列出的元素数,1–2000,缺省 150

observe find

在当前界面按文字、正则、资源 ID、描述或类名查找元素,并给出在当前界面唯一的选择器建议。

参数说明
--text <TEXT>文字包含,不区分大小写
--regex <REGEX>正则,匹配文字或描述
--id <ID>资源 ID,可省略包名
--desc <DESC>描述包含,不区分大小写
--class <CLASS>类名,可省略包名
--max <MAX>最多返回的命中数,1–100,缺省 20
--all同时在屏幕外与不可见的元素中查找

observe screenshot

截图(默认写文件 screenshot.png,或 --out -)

参数说明
--out <OUT>保存截图的路径;写 - 时输出到标准输出;缺省 screenshot.png
--max-edge <MAX_EDGE>长边像素,256–2048;给出缩放、格式、质量或标注参数之一时按这些参数处理
--image-format <IMAGE_FORMAT>图像格式:jpeg 或 png;缺省按 --out 的扩展名;取值:jpeg、png
--quality <QUALITY>JPEG 质量 1–100,缺省 75
--annotate在图上标出最近一次读取界面的元素编号

observe status

自动化就绪与能力位。

ui

UI 控制(点击 / 滑动 / 输入 / 按键 / 等待);动作没做成时结果照常输出,退出码为 3。

ui tap

点击(优先按元素定位,没有可用元素时用坐标)

参数说明
--element <ELEMENT>快照内元素标识
--snapshot <SNAPSHOT>元素所属快照版本(配合 --element,取自 observe inspect 首行)
--resource-id <RESOURCE_ID>resource-id 选择器
--text <TEXT>文本选择器
--desc <DESC>描述(content-desc)选择器
--at <AT>归一化坐标 x,y(0..1),没有可用元素时使用
--long-press-ms <LONG_PRESS_MS>长按毫秒数
--verify判定动作是否生效(界面有没有变化)

ui swipe

滑动(归一化坐标 x,y)

参数说明
--from <FROM>必填;起点 x,y(0..1)
--to <TO>必填;终点 x,y(0..1)
--duration-ms <DURATION_MS>滑动时长,毫秒;缺省 300
--verify判定动作是否生效(界面有没有变化)

ui type

向焦点(或 --element 指定)输入文本。

参数说明
<TEXT>必填;要输入的文本
--clear输入前清空
--submit输入后发送回车(提交搜索或表单)
--verify判定动作是否生效(界面有没有变化)
--element <ELEMENT>目标元素(缺省为当前焦点)
--snapshot <SNAPSHOT>元素所属快照版本(配合 --element,取自 observe inspect 首行)

ui key

发送按键(Android 按键码,如 66 回车、4 返回)

参数说明
<CODE>必填;Android 按键码
--verify判定动作是否生效(界面有没有变化)

ui wait

等待一个条件成立:元素出现(缺省)、--gone 元素消失、--idle-ms 界面不变、--animation 动画结束或 --package 应用到前台。

参数说明
--element <ELEMENT>快照内元素标识
--snapshot <SNAPSHOT>元素所属快照版本(配合 --element,取自 observe inspect 首行)
--resource-id <RESOURCE_ID>resource-id 选择器
--text <TEXT>文本选择器
--desc <DESC>描述(content-desc)选择器
--at <AT>归一化坐标 x,y(0..1),没有可用元素时使用
--timeout-ms <TIMEOUT_MS>等待上限,毫秒(最长 30000);缺省 5000
--gone等待选择器指定的元素消失
--idle-ms <IDLE_MS>等待界面保持不变的毫秒数
--animation等待动画结束
--package <PACKAGE>等待该应用到前台
--activity <ACTIVITY>与 --package 同用:等待该页面到前台

ui editor

触发编辑器动作(如搜索/前往)

参数说明
<ACTION>必填;输入法动作编号,如 2 前往、3 搜索、4 发送、6 完成

ui clear

清空当前焦点输入框。

ui batch

一次提交多步界面与应用动作并逐步执行(步骤结构与流程宏相同,最多 50 步、60 秒)

参数说明
<FILE>必填;步骤文件(.json 或 .yaml):步骤数组,或含 steps 的对象
-e, --var <NAME=值>变量,写作 NAME=值,可重复;优先于环境变量 YUNYOO_VAR_NAME 与文件里的缺省值
--keep-going某步失败或偏离后继续执行后面的步骤
--inspect-at-end结束时附上紧凑快照
--from <FROM>从第几步开始(从 1 起),用于偏离或确认后续跑
--confirmation <CONFIRMATION>已批准的确认单编号,与 --from 一起续跑

app

应用(列举 / 安装 / 启动 / 停止 / 清除 / 卸载)

app list

列举设备已安装应用。

app install

从应用库安装(或 --local 下以 --apk 安装本机 APK)

参数说明
<IDS>...应用库条目 id(可多个)
--apk <APK>本机 APK/XAPK/APKS 文件(仅 --local,本地节点上的环境)

app launch

启动应用。

参数说明
<PACKAGE>必填;应用包名
--activity <ACTIVITY>要启动的页面,缺省为应用的启动页

app stop

停止应用。

参数说明
<PACKAGE>必填;应用包名

app clear

清除应用数据。

参数说明
<PACKAGE>必填;应用包名

app update

更新应用到应用库的当前生效版本。

参数说明
<PACKAGE>必填;应用包名

app uninstall

卸载应用。

参数说明
<PACKAGE>必填;应用包名
--keep-data保留应用数据

file

文件(拉取)

file pull

从设备拉取文件(云端为异步任务;--local 下同步保存到 --out)

参数说明
<PATH>必填;设备上的文件路径
--out <OUT>本机保存位置(仅 --local;缺省为当前目录下的同名文件)

file push

把本机文件推到设备(缺省推到 /sdcard/Download/)

参数说明
<LOCAL>必填;本机文件路径
<REMOTE>设备上的目标路径或目录

backup

备份与可移植包(列表、创建、还原、封装导出、下载、导入、分享)

backup list

列出当前环境的备份。

backup create

为环境创建备份;--app 只备份该应用的数据。

参数说明
<ENV>环境标识;缺省取 --env 或 --device,都没给时取当前选中环境
--app <APP>应用包名:只做该应用的应用级备份
--name <NAME>备份名称
--wait等待备份结束

backup restore

用当前环境的一份备份还原:整机备份在下次开机时还原,应用级备份立即还原该应用。

参数说明
<BACKUP_ID>必填;备份 id
--account-password <ACCOUNT_PASSWORD>账号密码(备份里的设备身份与环境当前身份不同时平台复核;缺省从 WP_ACCOUNT_PASSWORD 读取)
--ignore-version应用级还原不检查版本
--wait应用级还原等待任务结束

backup export

把一份备份封装为 .wp 包并下载到本地。

参数说明
<BACKUP_ID>必填;备份 id
--out <OUT>输出文件(缺省用平台文件名)
--no-seed不随包携带身份种子
--no-secure-state不随包携带安全状态
--account-password <ACCOUNT_PASSWORD>账号密码(携带种子时平台复核;缺省从 WP_ACCOUNT_PASSWORD 读取)

backup share

为包创建分享链接(领取一律要求登录)

参数说明
<PACKAGE_ID>必填;包 id
--expires-hours <EXPIRES_HOURS>有效小时数;缺省 24
--max-downloads <MAX_DOWNLOADS>最多下载次数;缺省 5
--identity-transfer允许接收方导入后改持包内设备身份(含种子的包必须加)

backup package

把一份备份封装为 .wp 包(平台密封,不需要口令;平台尚未开启密封导出时按旧格式从 WP_PASSPHRASE 或标准输入读口令)

参数说明
<BACKUP_ID>必填;备份 id
--no-seed不随包携带身份种子(数据类包默认携带并需账号密码复核)
--no-secure-state不随包携带安全状态(整机类包默认携带;不带时该包不能用于新建环境)
--account-password <ACCOUNT_PASSWORD>账号密码(携带种子时平台复核;缺省从 WP_ACCOUNT_PASSWORD 读取)
--wait等待封装完成并打印包详情

backup pull

下载包到本地。

参数说明
<PACKAGE_ID>必填;包 id
--out <OUT>输出文件(缺省用平台文件名)

backup push

上传本地 .wp,由平台预检后导入到目标环境(旧口令包从 WP_PASSPHRASE 或标准输入读口令,只在本机派生 wrap_key)

别名:import

参数说明
<FILE>必填;.wp 文件
--mode <MODE>导入模式:restore | data-env | app | profile;缺省 restore
--name <NAME>data-env 模式的数据环境名
--new-env以环境包新建环境(不需要 --env;须给出 --sku)
--sku <SKU>新建环境的 SKU id(须与包的机型和 Root 变体一致)
--proxy <PROXY>新建环境绑定的代理 id
--attestation <ATTESTATION>新建环境的证明来源:pool 或 user:<keyboxId>
--title <TITLE>新建环境的名称
--egress-confirm <EGRESS_CONFIRM>预检返回的出口确认令牌(代理与包内锚点需确认时使用)
--dry-run只做预检:输出 plan,不创建导入任务
--identity-transfer确认把包内设备身份转移到目标环境(自动化导入改持包内身份时必需)
--bind-ack目标环境已绑定而包的来源未绑定时确认导入(绑定应用之外的第三方应用会被停用)
--wait等待导入任务结束

run

命令执行逃生舱(需显式授权)

参数说明
--shell以 shell 语义执行(整串作为单一参数)
--async异步执行(返回任务 id)
--timeout-ms <TIMEOUT_MS>超时毫秒
<ARGV>...必填;命令与参数(argv;置于 -- 之后)

connect

受控本地通道桥接逃生舱(需显式授权);建本地端口供本机调试工具接入。

参数说明
--port <PORT>本地监听端口;缺省 15555

batch

批量:对选择器选中的多台执行同一动作。

参数说明
--group <GROUP>选择器:分组 id
--tag <TAG>选择器:标签 id
--envs <ENVS>选择器:显式环境 id 集;可重复

batch run

对每台执行命令。

参数说明
--shell以 shell 语义执行(整串作为单一参数)
--async异步执行(返回任务 id)
--timeout-ms <TIMEOUT_MS>超时毫秒
<ARGV>...必填;命令与参数(argv;置于 -- 之后)

batch launch

对每台启动应用。

参数说明
<PACKAGE>必填;应用包名

batch stop

对每台停止应用。

参数说明
<PACKAGE>必填;应用包名

batch ui

对每台执行界面动作。

batch ui tap

点按(多台设备只能按文字、资源 ID、描述或坐标定位)

参数说明
--element <ELEMENT>快照内元素标识
--snapshot <SNAPSHOT>元素所属快照版本(配合 --element,取自 observe inspect 首行)
--resource-id <RESOURCE_ID>resource-id 选择器
--text <TEXT>文本选择器
--desc <DESC>描述(content-desc)选择器
--at <AT>归一化坐标 x,y(0..1),没有可用元素时使用
--long-press-ms <LONG_PRESS_MS>长按毫秒数

batch ui type

向焦点输入文本。

参数说明
<TEXT>必填;要输入的文本
--clear输入前清空
--submit输入后发送回车

batch ui key

发送按键(Android 按键码)

参数说明
<CODE>必填;Android 按键码

batch ui swipe

滑动(归一化坐标 x,y)

参数说明
--from <FROM>必填;起点 x,y(0..1)
--to <TO>必填;终点 x,y(0..1)
--duration-ms <DURATION_MS>滑动时长,毫秒;缺省 300

macro

宏录制与回放。

macro check

校验宏文件的格式,并列出运行时要传入的变量与密码占位。

参数说明
<FILE>必填;宏文件(.json 或 .yaml)
-e, --var <NAME=值>变量,写作 NAME=值,可重复

macro run

运行宏;1.0 版宏照原方式回放。

参数说明
<FILE>必填;宏文件(.json 或 .yaml)
-e, --var <NAME=值>变量,写作 NAME=值,可重复;优先于环境变量 YUNYOO_VAR_NAME 与文件里的缺省值
--from <FROM>从第几步开始(从 1 起),用于偏离或确认后续跑
--confirmation <CONFIRMATION>已批准的确认单编号,与 --from 一起续跑

macro save

从一次运行记录生成宏草稿。

参数说明
--run <RUN>必填;运行编号,见 report show
-o, --output <OUTPUT>写入的文件(.json、.yaml);不给时输出到屏幕

macro migrate

把 1.0 版宏转成 2.0。

参数说明
<FILE>必填;1.0 版宏文件
-o, --output <OUTPUT>写入的文件(.json、.yaml);不给时输出到屏幕

macro new

生成 2.0 宏模板(.json 或 .yaml)

参数说明
<FILE>必填;要生成的宏文件,扩展名决定格式

job

平台异步任务(开关机、备份、文件推拉、应用安装、流程宏)

job get

查询任务的状态与结果:平台任务为数字,本机流程任务以 job_ 开头。

参数说明
<ID>必填;任务编号

report

运行报告。

report show

查看一次运行的报告;不给运行编号时取最近一次,--device 只看该设备。

参数说明
<RUN>运行编号

confirm

确认单:等待决定、撤回或查看;批准只能由人在网页端或桌面端操作。

confirm wait

等待确认单的决定(单次最长 60 秒)

参数说明
<ID>必填;确认单编号
--wait-ms <WAIT_MS>最长等待毫秒,0–60000;缺省 30000

confirm cancel

撤回一张还在等待的确认单。

参数说明
<ID>必填;确认单编号

confirm show

查看确认单的当前状态。

参数说明
<ID>必填;确认单编号

handoff

请用户接手设备(付款、登录、验证码这类要本人处理的界面);不带 --reason 时只查询当前状态。

参数说明
--reason <REASON>需要用户处理的原因

config

配置(端点 / Profile)

config show

显示生效配置。

config set-profile

设置默认 profile。

参数说明
<NAME>必填;profile 名称

config set-endpoint

设置某 profile 的端点。

参数说明
<PROFILE>必填;profile 名称
<ENDPOINT>必填;平台端点地址

completions

生成 shell 补全脚本。

参数说明
<SHELL>必填;shell 类型;取值:bash、elvish、fish、powershell、zsh

mcp

以 MCP server 模式运行(stdio,供 AI agent 接入)

参数说明
--tools <组>只提供这些组的工具(逗号分隔),缺省为全部被允许的组;取值:core、apps、files、lifecycle、backups、macros、escape;可重复