命令行参考
最近更新: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;可重复 |
