roborock-cli

An unofficial CLI for Roborock vacuum robots — control your vacuum from the terminal.

Note: This tool communicates only with the official Roborock cloud API. It does not collect, transmit, or store any personal data beyond what is necessary to authenticate with Roborock on your behalf.

Features

• 🔐 Email/password and email-code login
• 📋 List and select devices
• ▶️ Start / Pause / Dock
• 📊 Device status
• 🔄 Session refresh (heartbeat)
• 📡 JSON output for all commands

Privacy & Data

• No personal data is included in this repository (no email addresses, passwords, or account-specific configuration).
• No user data is uploaded or shared with any service other than the official Roborock API.
• All sensitive credentials are stored locally only, in:
  • ~/.roborock-cli/credentials.json — session token and account info (mode 0600)
  • ~/.roborock-cli/home.json — device list cache
  • ~/.roborock-cli/device-id.txt — anonymous local device identifier

Installation

Requires Node.js 18+ and npm.

git clone https://github.com/lu-zhengda/roborock-cli.git
cd roborock-cli
npm install
npm run build

Run directly from the project directory:

node dist/index.js --help

Or create a local alias / symlink:

# Option A: npm link (local only, no global registry upload)
npm link

# Option B: shell alias
alias roborock="node /path/to/roborock-cli/dist/index.js"

Setup

roborock login
# Enter your Roborock app email and password (or email verification code)

Commands

Authentication

roborock login              # Authenticate with Roborock
roborock logout             # Clear credentials
roborock auth-status        # Check auth status

Device Management

roborock devices            # List all devices
roborock devices --json     # JSON output

Control

roborock start              # Start cleaning
roborock pause              # Pause cleaning
roborock dock               # Return to dock

Status

roborock status             # Show device status
roborock status --json      # JSON output for automation

Session Refresh

roborock heartbeat          # Refresh session token if needed

JSON Output

All commands support --json for programmatic use:

roborock devices --json | jq '.[0].name'
roborock status --json | jq '.battery'

Requirements

• Roborock account (email/password)
• Vacuum connected to Roborock app

Disclaimer

See DISCLAIMER.md for legal notices, warranty disclaimer, and Terms of Service requirements.

Security

See SECURITY.md for credential storage policy and how to report vulnerabilities.

License

MIT