> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI 概览

> Wuji CLI 的定位、命令一览与设计理念

Wuji CLI 是面向终端、脚本和 AI Agent 的 Wuji 设备命令行工具。不离开终端即可扫描设备、探测连通性、读写参数、订阅实时数据、标定触觉、运行健康诊断和升级固件。

## 命令一览

| 命令 | 作用 |
| - | - |
| `wuji devices` | 扫描并列出设备（USB/UDP） |
| `wuji ping` | 握手探测设备连通性，报告 SN、固件版本和 IP |
| `wuji resources` | 列出设备的可读写参数与可订阅 topic |
| `wuji get <path>` | 读取参数 |
| `wuji set <path> <value>` | 写入参数 |
| `wuji user` | 管理用户 Profile 与标定数据导入导出 |
| `wuji calib hand-model` | 引导式手部模型标定 |
| `wuji sub <topic>` | 订阅实时数据 |
| `wuji calib tactile` | 引导式标定手套触觉，训练并安装接触模型 |
| `wuji doctor` | 设备健康自检 |
| `wuji logs` | 查看、筛选并导出日志支持包 |
| `wuji upgrade` | 检查并升级设备固件 |
| `wuji update` | 更新 CLI 到最新版本 |
| `wuji completions <shell>` | 生成 shell 自动补全脚本 |

在任意命令后加 `--help` 查看详细帮助。

## 设计理念

* **无状态**：每条命令独立完成「连接 → 操作 → 断开」，命令之间不保持连接，无需先"连接"再操作。
* **占用时只读降级**：设备固件同一时刻只允许一个直连会话。设备被其它宿主应用占用时，CLI 自动切换为只读访问，此时 `set` 写操作会被拒绝。
* **退出码可脚本化**：0 表示成功，非 0 表示失败。`ping` 任一设备失败、`doctor` 诊断出故障均返回 1，可直接用于脚本判定。

## 输出模式

所有命令默认以表格或树形报告输出。附加全局参数可切换为结构化输出：

| 参数 | 输出形式 | 适用场景 |
| - | - | - |
| `--json` | 格式化 JSON | 脚本解析、AI Agent 读取 |
| `--jsonl` | 每帧一行紧凑 JSON | 流数据采集、管道处理 |

### 错误输出

`--json` / `--jsonl` 下，命令错误以固定结构的 JSON 输出到 stderr，stdout 只输出数据。该 JSON 对象含 `message`（完整错误链）与 `argv`（本次调用的原始参数数组）：

```json theme={null}
{
  "error": {
    "argv": ["wuji", "get", "...", "--json"],
    "message": "..."
  }
}
```

参数解析错误同样输出该结构，退出码为 2。脚本判断成败以退出码为准（0 成功，非 0 失败），不要靠解析 stdout 判断：

```bash theme={null}
wuji get <path> --json 2>&1 | jq .error.message   # 合并 stderr 后提取错误信息
wuji get <path> --json 2>/dev/null                # 丢弃错误输出，stdout 保持纯净
```

[`wuji user`](/docs/wuji-cli/user) 和 [`wuji calib hand-model`](/docs/wuji-cli/hand-model-calibration) 的错误自带 `code` 字段与分档退出码，且输出到 stdout 而非 stderr，与通用错误结构不同，见各自命令页的「自动化调用」。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.