UU远程 CLI 怎么用？命令行控制设备、云电脑和远程协助

通过 uuyc-cli，可以在终端中查询设备、发起远控、管理云电脑、操作远程终端和远程协助，也可以使用 --json 输出结构化结果，方便脚本读取。

适用设备与版本

不同主控端的 CLI 能力如下：

主控端	版本与支持情况
Windows 主控端	支持本文介绍的新版 CLI 命令，UU远程 V4.43.0 及以上
macOS 主控端	原有 CLI 能力保留；本次新版命令调整暂未同步
被控端	Windows、macOS，具体能力以命令返回结果为准
适用场景	同账号远控和远程协助

这个功能适合什么场景

• 查询设备并通过设备 ID 发起远程控制。
• 管理云电脑、远程终端和本机终端会话。
• 使用命令行配置远程协助，并将查询结果接入脚本。

详细教程

1. 找到 CLI

Windows 默认不会把 CLI 加入系统 PATH，也不要假定固定安装目录。打开 PowerShell，执行以下命令读取 UU远程实际安装目录，并将 CLI 路径保存到 $cli：

$instDir = (Get-ItemProperty 'HKLM:\SOFTWARE\Netease\GameViewerSetup' -Name instDir).instDir
$cli = Join-Path $instDir 'bin\uuyc-cli.exe'
& $cli --version

如果 uuyc-cli 已经加入 PATH，也可以直接使用 uuyc-cli。如需修改用户级 PATH，请先确认后再操作。终端出现乱码时，可以先执行 chcp 65001。

2. 检查 CLI 和登录状态

& $cli echo
& $cli status --json

echo 成功表示 CLI 可以与主应用通信。status --json 可以查看 serviceStatus、networkStatus 和 isLoggedIn 等信息。--version 不要求主应用运行；大多数查询和控制命令需要主应用保持运行，部分命令还需要先登录。

3. 查询设备并发起远控

先查询可连接的普通设备：

& $cli device list --json

在 data.items 中找到目标设备的 deviceId，并确认 isOnline 为 true。设备名称只用于展示，不能代替设备 ID。

使用设备 ID 发起连接：

& $cli device connect DEVICE_ID --json
& $cli device status --json

device connect 是异步提交命令，返回成功只表示请求已提交。继续查看 data.connections 中对应设备的 connectionState：

• connecting：正在连接。
• connected：已连接。
• failed：连接失败，可结合 lastError 排查。

断开指定设备：

& $cli device disconnect DEVICE_ID --json

4. 管理云电脑

查询云电脑：

& $cli cloudpc list --json

云电脑的开机、关机和连接都是异步操作，需要使用 cloudpc info 查询进展：

& $cli cloudpc launch CLOUD_PC_ID --json
& $cli cloudpc info CLOUD_PC_ID --json

确认 powerState 为 running 后，再连接云电脑：

& $cli cloudpc connect CLOUD_PC_ID --json

关闭云电脑必须指定云电脑 ID：

& $cli cloudpc shutdown CLOUD_PC_ID --json

cloudpc status 只查询远控连接状态，不显示开关机进展。需要断开云电脑连接时，使用 cloudpc disconnect CLOUD_PC_ID；省略 ID 会断开全部云电脑连接。

5. 管理远程终端和本机终端

term 管理被控设备的终端会话，每条命令都要带设备 ID：

命令	作用
uuyc-cli term -d DEVICE_ID new SESSION_NAME	新建远程终端会话
uuyc-cli term -d DEVICE_ID attach SESSION_NAME	接入已有会话
uuyc-cli term -d DEVICE_ID list --json	查看指定设备的会话
uuyc-cli term -d DEVICE_ID has SESSION_NAME --json	判断会话是否存在且可接入
uuyc-cli term -d DEVICE_ID rename OLD_NAME NEW_NAME --json	重命名会话
uuyc-cli term -d DEVICE_ID kill SESSION_NAME --json	结束会话

新建或接入会话会接管当前交互式终端，不支持 --json。Windows 被控端可以通过 --shell powershell 或 --shell cmd 指定 Shell；被控端要求解锁时，即使添加 --json 也可能需要输入密码。

lterm 管理本机终端会话，不需要设备 ID：

命令	作用
uuyc-cli lterm new SESSION_NAME	新建并进入本机终端会话
uuyc-cli lterm attach SESSION_NAME	接入本机会话
uuyc-cli lterm list --json	查看本机会话
uuyc-cli lterm has SESSION_NAME --json	判断本机会话是否可接管
uuyc-cli lterm rename OLD_NAME NEW_NAME --json	重命名本机会话
uuyc-cli lterm kill SESSION_NAME --json	结束本机会话

lterm new 和 lterm attach 要求交互式 TTY。脚本或 Agent 查询会话时，请使用 list 或 has。

6. 使用远程协助命令

本机协助设置不要求登录，向其他设备发起协助需要登录：

命令	作用
uuyc-cli assist id --json	获取本机协助 ID
uuyc-cli assist reset-code --json	刷新临时验证码
uuyc-cli assist set-code CODE --json	设置自定义验证码
uuyc-cli assist set-code --code-stdin --json	从标准输入读取验证码
uuyc-cli assist allow on --json	开启允许他人远程协助本机
uuyc-cli assist allow off --json	关闭允许他人远程协助本机
uuyc-cli assist start ASSIST_ID CODE --json	向其他设备发起远程协助
uuyc-cli assist status ASSIST_ID --json	查询远程协助进展

通过 --code-stdin 输入验证码，可以避免验证码出现在命令历史、进程列表或共享日志中。assist start 提交成功不代表已经接管，需要继续查询 assist status。

输出格式与退出码

默认输出为人类可读文本；需要脚本解析时，在支持的命令后添加 --json。成功结果写入标准输出，错误信息写入标准错误。

退出码	含义
0	操作成功；has 命令表示目标存在且可用
1	term has 或 lterm has 判断为否，不代表服务异常
2	命令或参数用法错误
101	尚未登录
102	无法连接主应用或终端服务
104	参数无效、缺失或会话名已被占用
105	查询超时、响应不可用或解析失败
106	设备或终端会话不存在
108	当前环境无法接管终端
110	普通设备离线
118 / 119	远程协助验证超时或失败

判断异步命令是否完成时，不要只看命令提交是否成功，应继续查询对应状态。

macOS 端说明

macOS 原有 CLI 能力保留，但本次新版命令契约的新增和调整目前只上线 Windows。本文中的新版命令表、Windows 安装路径和 Windows term 行为不能直接作为 macOS 操作指引，macOS 的具体版本、路径和命令差异以后续客户端版本为准。

常见问题

Windows 提示找不到 uuyc-cli，怎么办？

Windows 默认不会把 CLI 加入 PATH。请先执行 where.exe uuyc-cli；如果找不到，按本文“找到 CLI”步骤读取实际安装目录，并使用 & $cli 调用。

device connect 返回成功，为什么还没有连上？

device connect 是异步提交命令。请继续执行 uuyc-cli device status --json，直到对应设备的 connectionState 变为 connected。

device connect 应该填写设备名还是设备 ID？

请填写设备 ID。先执行 uuyc-cli device list --json，从 data.items[].deviceId 获取；设备名称不能代替设备 ID。

如何判断 has 命令的结果？

退出码为 0 表示目标存在且可用，退出码为 1 表示判断结果为否。判断 has 时请读取对应字段和退出码，不要只看 JSON 顶层的 success。

macOS 可以使用本文的新版命令吗？

不能直接套用。macOS 原有 CLI 能力仍保留，但本文所述新版命令调整目前只上线 Windows。

如何在 Windows 终端中使用 CMD 命令？

新建远程终端会话时指定 --shell cmd，例如：

& $cli term -d DEVICE_ID new SESSION_NAME --shell cmd

如果使用默认 PowerShell，请改用 PowerShell 语法。

注意事项

• 普通设备和云电脑使用各自的资源 ID；term 还需要设备 ID 和会话名称，lterm 只使用本机会话名称。
• device disconnect 不带 ID 会断开全部普通设备连接；cloudpc disconnect 不带 ID 会断开全部云电脑连接，请确认目标范围后再执行。
• cloudpc shutdown 必须指定云电脑 ID，不会因为省略 ID 而执行全部关机。
• device connect、cloudpc launch、cloudpc shutdown、cloudpc connect 和 assist start 都需要继续查询对应状态。
• --json 只适用于帮助中标明支持的命令；term new/attach 和 lterm new/attach 需要接管交互式终端，不支持 --json。
• 远程协助验证码属于敏感信息，建议使用 --code-stdin 输入。

交流与咨询

如果在 CLI 使用过程中遇到命令报错、版本兼容或远程控制问题，可以扫码加入交流群，与其他用户交流。