Metadata-Version: 2.4
Name: ubox-cli
Version: 0.0.1
Summary: UBox CLI工具 - 通过命令行操作UBox设备自动化能力
Requires-Python: <3.12,>=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: ubox-py-sdk==0.2.23.post2
Description-Content-Type: text/markdown

# UBox CLI 工具

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

## 前置依赖

本项目需要 Python >=3.10,<3.12，推荐使用 [uv](https://docs.astral.sh/uv/) 进行安装和管理。

### 安装 uv

```bash
# 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"
```

## 安装

```bash
# 方式1：从 wheel 文件安装
uv tool install --python 3.10.12 ubox_cli-0.2.0-py3-none-any.whl --index-url https://pypi.tuna.tsinghua.edu.cn/simple

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

## 快速上手

### 1. 配置认证

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

```bash
cp env.example .env
```

```bash
UBOX_AUTH_TOKEN=your_token
```

### 2. 获取设备列表

```bash
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`

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

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

### 4. 执行操作

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

```bash
# 截图（使用默认设备）
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` 参数）：

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

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

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

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

### 5. 查看已连接设备

```bash
ubox-cli device status
```

### 6. 断开设备

```bash
# 断开默认设备
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 文件** 设置：

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|---------|--------|------|
| Auth Token | `UBOX_AUTH_TOKEN` | - | Token 认证（必填） |
| 环境 | `UBOX_ENV` | `formal` | `formal` \| `test` |

## 获取帮助

```bash
# 查看所有命令组
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
```