# Roborock CLI — Developer Debug Tool A standalone CLI to interact with the Roborock API and control vacuum devices directly, without running the full Matterbridge plugin. Useful for debugging, testing API responses, and sending commands during development. --- ## Setup Build the project first: ```bash npm run build ``` --- ## Usage ```bash npm run cli -- --command [--duid ] [--debug] ``` | Option | Description | | --------- | ----------------------------------------------------- | | `--help` | Show help message | | `--debug` | Enable debug logging | | `--local` | Send commands via local network (TCP) instead of MQTT | --- ## Commands | Command | Arguments | Description | | ------------------------------- | ------------------------------------------------------------ | ------------------------------- | | [`login`](#login) | — | Authenticate and save session | | [`devices`](#devices) | — | List all devices | | [`status`](#status) | `--duid ` | Get device status via MQTT | | [`start`](#start) | `--duid ` | Start cleaning | | [`stop`](#stop) | `--duid ` | Stop cleaning | | [`pause`](#pause) | `--duid ` | Pause cleaning | | [`resume`](#resume) | `--duid ` | Resume cleaning | | [`ping`](#ping) | `--duid ` | Beep robot (find_me) | | [`clean-mode`](#clean-mode) | `--duid ` | Get current clean mode settings | | [`room-info`](#room-info) | `--duid ` | Get room mapping (active map) | | [`map-info`](#map-info) | `--duid ` | Get all maps with rooms | | [`scenes`](#scenes) | `--duid [--detail]` | List cleaning scenes/routines | | [`network-info`](#network-info) | `--duid ` | Get WiFi/network info | | [`custom`](#custom) | `--duid --method [--params ] [--send true]` | Send/get custom command | | [`--help`](#help) | — | Show help message | --- ### `login` Authenticate with your Roborock account. Sends a verification code to your email. ```bash npm run cli -- --command login ``` Prompts: ``` Email: your@email.com Sending verification code... Verification code: 123456 ``` On success, saves session to `.cli-session.json` and lists discovered devices: ``` Logged in as: your@email.com Session saved. Found 2 device(s). • abc123 Living Room Vacuum model=roborock.vacuum.a08 pv=A01 • def456 Bedroom Vacuum model=roborock.vacuum.a15 pv=B01 ``` > Session is stored locally in `.cli-session.json` (gitignored). Re-run `login` if the session expires. --- ### `devices` List all devices in your home. Refreshes the device list in the session. ```bash npm run cli -- --command devices ``` Output: ``` Found 2 device(s): duid: abc123 name: Living Room Vacuum model: roborock.vacuum.a08 pv: A01 online: true duid: def456 name: Bedroom Vacuum model: roborock.vacuum.a15 pv: B01 online: false ``` --- ### `status` Get the current status of a device via MQTT. ```bash npm run cli -- --command status --duid ``` Example: ```bash npm run cli -- --command status --duid abc123 ``` Output: ```json Device status: { "state": 8, "battery": 100, "clean_time": 0, ... } ``` --- ### `start` Start cleaning. ```bash npm run cli -- --command start --duid ``` --- ### `stop` Stop cleaning and return to dock. ```bash npm run cli -- --command stop --duid ``` --- ### `pause` Pause cleaning in place. ```bash npm run cli -- --command pause --duid ``` --- ### `resume` Resume cleaning after pause. ```bash npm run cli -- --command resume --duid ``` --- ### `ping` Beep the robot to locate it (`find_me`). ```bash npm run cli -- --command ping --duid ``` --- ### `clean-mode` Get the current clean mode settings (suction power, water flow, mop route). ```bash npm run cli -- --command clean-mode --duid ``` Output: ``` Clean mode for device abc123: suction_power: 102 water_flow: 200 distance_off: 0 mop_route: 300 sequence_type: (not supported) ``` --- ### `scenes` List all cleaning scenes/routines configured for the device's home. Use `--detail` to include the raw `param` field. ```bash npm run cli -- --command scenes --duid npm run cli -- --command scenes --duid --detail ``` Output: ``` Scenes for device abc123: id=1 name=Daily Clean type=cleanScene enabled=true id=2 name=Bedroom type=cleanScene enabled=false ``` --- ### `room-info` Get room mapping for a device. Shows room IDs, tags, and names — useful for debugging room IDs before using room-based cleaning. ```bash npm run cli -- --command room-info --duid ``` Output (multi-map device): ``` Room mapping for device abc123: Map: Default Map 1 (id=0) id=16 tag=4 iot_name_id=abc name=Living Room id=17 tag=5 iot_name_id=def name=Kitchen ``` Output (fallback for devices without multi-map support): ``` Room mapping for device abc123: Room mapping (fallback): id=16 tag=4 iot_name_id=abc name=Living Room ``` --- ### `map-info` Get map info for a device. Shows all maps with their IDs, names, and room-info per map. ```bash npm run cli -- --command map-info --duid ``` Output: ``` Map info for device abc123: Map: Default Map 1 (id=0) room-info=2 id=16 tag=4 iot_name_id=abc name=Living Room id=17 tag=5 iot_name_id=def name=Kitchen ``` --- ### `network-info` Get WiFi and network info for a device (SSID, IP, MAC, BSSID, signal strength). ```bash npm run cli -- --command network-info --duid ``` Output: ``` Network info for device abc123: ssid: MyWiFi ip: 192.168.1.42 mac: AA:BB:CC:DD:EE:FF bssid: 11:22:33:44:55:66 rssi: -55 dBm ``` > Note: Not supported on all device protocols (Q7, Q10). Returns a message if unsupported. --- ### `custom` Send or get a custom MQTT command with optional params. | Argument | Required | Description | | ------------- | -------- | --------------------------------------- | | `--duid` | yes | Device ID | | `--method` | yes | RPC method name (e.g. `get_status`) | | `--params` | no | JSON-encoded params array or object | | `--send true` | no | Fire-and-forget (default: get response) | **Get response:** ```bash npm run cli -- --command custom --duid --method get_status ``` ```bash npm run cli -- --command custom --duid --method get_clean_summary --params '[{"start_time":0}]' ``` Output: ```json Response: { "clean_time": 3600, "clean_area": 12000, ... } ``` **Fire-and-forget (send only, no response):** ```bash npm run cli -- --command custom --duid --method set_clean_motor_mode --params '[{"fan_power":102}]' --send true ``` Output: ``` Sent: set_clean_motor_mode ``` --- ### `help` Show all available commands and examples. ```bash npm run cli -- --help ``` --- ## Typical Workflow ```bash # 1. Build npm run build # 2. Login once npm run cli -- --command login # 3. List devices to get duid npm run cli -- --command devices # 4. Send commands npm run cli -- --command status --duid abc123 npm run cli -- --command room-info --duid abc123 npm run cli -- --command start --duid abc123 npm run cli -- --command pause --duid abc123 npm run cli -- --command stop --duid abc123 # 5. Debug mode (verbose logging) npm run cli -- --command status --duid abc123 --debug ``` --- ## Session File After `login`, credentials are cached in `.cli-session.json` at the project root. This file is gitignored and contains your `UserData` and device list. Delete it to force re-login. --- ## Notes - Commands that control the vacuum (`status`, `start`, `stop`, `pause`) connect via MQTT and time out after **10 seconds** if the device is unreachable. - Use `--local` to route commands over the local TCP connection (port 58867) instead of MQTT. The device IP is fetched automatically via `get_network_info`. Not supported on Q7/Q10 protocol devices. - The default authentication endpoint is `https://usiot.roborock.com` (US region). If your account is in EU/CN/RU, the API resolves the correct regional URL automatically after providing your email. - Log output is suppressed by default (level `DEBUG`). Internal API/MQTT logs will not appear unless there is a warning or error.