roborock-cli 0.1.6

Roborock 扫地机 CLI 控制工具

roborock-cli

Roborock 扫地机 CLI 控制工具。

功能

提供 15 个 CLI 命令，支持多设备（通过设备名称模糊匹配选择目标设备）。

查询命令（5 个）

命令	说明
roborock-cli devices	列出所有设备（名称、型号、DUID、固件版本）
roborock-cli status	设备精简状态（电量、清洁进度、耗材、房间列表等）
roborock-cli map	获取地图元数据和图片
roborock-cli routines	列出智能场景
roborock-cli auth	交互式认证（需要 TTY）

控制命令（10 个）

命令	说明
roborock-cli start-clean	开始清洁（全屋或指定房间）
roborock-cli stop-clean	停止清洁
roborock-cli pause-clean	暂停清洁
roborock-cli resume-clean	恢复清洁
roborock-cli go-home	回充电座
roborock-cli find-robot	寻找机器人（发出声音）
roborock-cli dock-action	基座操作（集尘/洗拖布）
roborock-cli set-volume	设置音量（0-100）
roborock-cli set-dnd	设置勿扰模式
roborock-cli execute-routine	执行智能场景

安装使用

前置：安装 uv

本项目通过 uvx 运行，需要先安装 uv：

macOS / Linux

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

Windows

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

安装后终端输入 uvx --version 验证。

通过 uvx（推荐）

1. 首次认证

uvx roborock-cli auth

按提示输入 Roborock 账户邮箱和验证码，认证信息保存在 ~/.cache/roborock-cli/。

2. 使用 CLI

# 列出设备
uvx roborock-cli devices

# 查看状态
uvx roborock-cli status

# 开始全屋清洁
uvx roborock-cli start-clean

# 开始房间清洁（房间 ID 通过 status 命令获取）
uvx roborock-cli start-clean -s 1 2 3

# 回充电座
uvx roborock-cli go-home

3. 查看帮助

所有命令都支持 -h 查看用法：

roborock-cli -h              # 查看所有可用命令
roborock-cli start-clean -h  # 查看子命令的参数说明

4. 更新版本

uvx --upgrade roborock-cli -V

永久安装到 PATH

不执行此步骤的话，所有命令都需要加 uvx 前缀，例如 uvx roborock-cli devices。

如果不想每次都加 uvx 前缀，可以永久安装：

uv tool install roborock-cli

之后直接使用裸命令：

roborock-cli devices
roborock-cli status
roborock-cli start-clean

更新已安装的版本：

uv tool upgrade roborock-cli

开发模式

# 需要先 clone python-roborock 到 ./python-roborock/
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

roborock-cli --help          # CLI 帮助
roborock-cli auth            # 认证

输出格式

CLI 命令默认输出 JSON 格式，便于程序解析：

{
  "count": 2,
  "devices": [
    {"name": "客厅扫地机", "duid": "abc123", "model": "roborock.vacuum.a75", "firmware": "02.00.01"},
    {"name": "卧室扫地机", "duid": "def456", "model": "roborock.vacuum.s8", "firmware": "02.00.02"}
  ]
}

错误退出码

退出码	含义
0	成功
1	通用业务错误
2	认证错误（需重新运行 roborock-cli auth）
3	设备错误
4	参数无效
5	内部错误

故障排除

Windows：应用程序控制策略阻止运行

如果在 Windows 上运行 uvx roborock-cli 出现以下错误：

error: Failed to query Python interpreter at `...\uv\cache\...\python.exe`
  Caused by: 应用程序控制策略已阻止此文件。 (os error 4551)

这是 Windows 安全策略阻止了 uv 缓存目录下的特定 Python 解释器。解决方法：

方法 1：清理 uv 缓存（推荐）

uv cache clean
uvx roborock-cli auth

方法 2：指定系统 Python

先从 python.org 安装 Python 3.12+，然后：

uvx --python python3.12 roborock-cli auth

方法 3：用 pip 直接安装

pip install roborock-cli
roborock-cli auth

要求

• Python >= 3.12
• Roborock 账户（国际版，邮箱注册）

许可证

GPL-3.0-only（由于 vendoring 了 python-roborock）