UBox CLI 工具

通过命令行操作 UBox 设备自动化能力，支持多设备管理。

前置依赖

本项目需要 Python >=3.10,<3.12，推荐使用 uv 进行安装和管理。

安装 uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装

# 方式1：从 wheel 文件安装
uv tool install --python 3.10.12 ubox_cli --index-url https://pypi.tuna.tsinghua.edu.cn/simple  --extra-index-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple

# 方式2：从源码安装
cd ubox-cli
uv sync

快速上手

1. 配置认证

复制 env.example 为 .env 并填入 Token：

cp env.example .env

UBOX_AUTH_TOKEN=your_token

2. 获取设备列表

ubox-cli device list
ubox-cli device list --platform android
ubox-cli device list --platform ios --page-size 10

3. 连接设备

连接设备后会按 UDID 自动保存连接信息到本地，后续操作无需手动传入：

所有设备连接信息统一保存在一个文件中：macOS ~/Library/Application Support/ubox-cli/connections.json，Linux ~/.config/ubox-cli/connections.json

# 连接第一台设备
ubox-cli device connect --udid DEVICE_UDID_1 --os-type android

# 连接第二台设备（支持同时管理多台）
ubox-cli device connect --udid DEVICE_UDID_2 --os-type ios

4. 执行操作

连接后直接执行命令，默认使用最后连接的设备：

# 截图（使用默认设备）
ubox-cli screen screenshot

# 点击元素
ubox-cli action click --loc "//button[@text='确定']"

# 输入文本
ubox-cli action input-text --text "hello"

# 按键操作
ubox-cli action press --button HOME

# 获取UI树
ubox-cli find ui-tree

操作指定设备（通过 --udid 参数）：

# 对第一台设备截图
ubox-cli screen screenshot --udid DEVICE_UDID_1

# 对第二台设备点击
ubox-cli action click --loc "//button[@text='OK']" --udid DEVICE_UDID_2

也可以手动指定连接信息（优先级最高）：

ubox-cli screen screenshot --conn-info '{"udid":"xxx","os_type":"android",...}'

5. 查看已连接设备

ubox-cli device status

6. 断开设备

# 断开默认设备
ubox-cli device disconnect

# 断开指定设备
ubox-cli device disconnect --udid DEVICE_UDID_1

7. 自动重连

当设备连接过期时，CLI 会自动尝试使用保存的 UDID 和系统类型重新连接，并更新对应设备的本地连接信息，无需手动干预。

命令结构

ubox-cli
├── device       设备管理
│   ├── list         获取可用设备列表
│   ├── connect      连接设备（按UDID保存）
│   ├── disconnect   断开设备连接
│   ├── status       查看所有已保存的连接
│   └── info         获取设备详细信息
├── app          应用管理
│   ├── start        启动应用
│   ├── stop         停止应用
│   ├── current      获取当前运行的应用
│   ├── running      获取运行中的应用列表
│   ├── install      通过URL安装应用
│   ├── install-local 安装本地应用文件
│   └── uninstall    卸载应用
├── action       交互操作
│   ├── click        智能点击（UI/CV/OCR/POS）
│   ├── click-pos    基于坐标点击
│   ├── long-click   长按操作
│   ├── slide        智能滑动
│   ├── slide-pos    基于坐标滑动
│   ├── input-text   输入文本
│   └── press        按键操作
├── screen       截图录制
│   ├── screenshot        截图保存到本地
│   ├── screenshot-base64 获取Base64格式截图
│   ├── record-start      开始屏幕录制
│   └── record-stop       停止屏幕录制
├── find         UI查找
│   ├── ui           UI控件查找
│   ├── ocr          OCR文字查找
│   └── ui-tree      获取UI树结构
├── clipboard    剪贴板操作
│   ├── set          设置剪贴板
│   └── get          获取剪贴板
├── debug        调试诊断
│   ├── adb             执行ADB命令（仅Android/鸿蒙）
│   ├── logcat-start    开始Logcat采集（仅Android/鸿蒙）
│   ├── logcat-stop-all 停止所有Logcat任务（仅Android/鸿蒙）
│   ├── logcat-list     列出Logcat任务（仅Android/鸿蒙）
│   ├── perf-start      开始性能采集
│   ├── perf-stop       停止性能采集
│   ├── anr-start       开始ANR/Crash监控（仅Android/鸿蒙）
│   └── anr-stop        停止ANR/Crash监控（仅Android/鸿蒙）
└── version      获取版本信息

配置项

所有配置通过 环境变量 或 .env 文件 设置：

获取帮助

# 查看所有命令组
ubox-cli --help

# 查看某个命令组的帮助
ubox-cli device --help
ubox-cli action --help
ubox-cli debug --help

# 查看具体子命令的帮助
ubox-cli device connect --help
ubox-cli action click --help
ubox-cli debug logcat-start --help