Devices

Dreo

pp-dreo

The only standalone CLI for Dreo smart-home devices — bulk control, live sensor streams, and a local history every...

Printed by @tmchow (Trevin Chow)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install dreo

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-dreo --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-dreo skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-dreo. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

The only standalone CLI for Dreo smart-home devices — bulk control, live sensor streams, and a local history every other Dreo tool throws away.

Every existing Dreo client is bundled inside Home Assistant or Homebridge; this is the first general-purpose CLI. It speaks the same WebSocket control protocol the reverse-engineered clients use, plus it keeps a local SQLite cache so bulk fan-out, cross-device sensor snapshots, sensor history, scenes, and alerts work even when the cloud is slow.

Printed by @tmchow (Trevin Chow).

Authentication

Dreo has no public developer API. Authentication uses your Dreo account email and password against the same OAuth endpoint the Dreo iOS app calls — the password is MD5-hashed before the wire, and the bearer token returned is cached locally.

Set these two env vars:

export DREO_USERNAME='your-dreo-account-email'
export DREO_PASSWORD='your-dreo-password'

Then run any command. The CLI exchanges credentials for an access token on first use, caches both the credentials and the bearer to ~/.config/dreo-pp-cli/config.toml at mode 0600, and reuses them. When the bearer expires it transparently re-logs in using the cached credentials — Dreo's OAuth flow has no refresh token, so caching the credentials is what lets cron jobs and unattended runs survive token expiry without re-exporting env vars every session. Region discovery (us/eu) happens automatically on first login; pin it with DREO_REGION=us to skip the round-trip.

Three ways to supply credentials:

Env vars (recommended): Set DREO_USERNAME and DREO_PASSWORD and run dreo-pp-cli auth login.

--password-stdin (scriptable, no leak): Pipe the password from a secret manager — Docker-style:

op read 'op://Personal/Dreo/password' | dreo-pp-cli auth login --username me@example.com --password-stdin
pass dreo/password         | dreo-pp-cli auth login --username me@example.com --password-stdin

--password <value> flag (insecure, warns): Supported for ergonomics, but auth login prints a stderr warning every time because the plaintext lands in /proc/<pid>/cmdline, ps aux, audit logs, and shell history. Use only when you understand the trade-off.

What's cached on disk. ~/.config/dreo-pp-cli/config.toml (mode 0600, in your home directory) contains:

username and password — the credentials you supplied via env vars (in plaintext, mirroring AWS CLI's ~/.aws/credentials and Stripe CLI's config conventions)
access_token — the OAuth bearer
region, token_expiry, timestamps — non-sensitive metadata

Treat the file as sensitive: don't commit it to a public repo, don't share it, and don't sync it to cloud-storage providers without encryption. Mode 0600 keeps it readable only by your user account. To wipe everything (credentials and token): dreo-pp-cli auth logout.

Useful commands:

dreo-pp-cli auth login — explicit login (also runs lazily on first authenticated command, and automatically on 401)
dreo-pp-cli auth status — current authentication state (doesn't reveal the token or password)
dreo-pp-cli auth logout — wipe cached token and persisted credentials
dreo-pp-cli doctor — verify everything end-to-end

Quick Start

# Verify credentials and login round-trip against the live API
dreo-pp-cli doctor

# See every device on your Dreo account with model, room, and online status
dreo-pp-cli devices list

# Whole-house temperature, humidity, and PM2.5 in one shot
dreo-pp-cli sensors --json

# Turn off every tower fan in one command — the bedtime ritual
dreo-pp-cli bulk --action off --type tower-fan

# Live WebSocket state stream as JSON lines — the realtime debug surface no other Dreo tool exposes
dreo-pp-cli watch --all

Unique Features

These capabilities aren't available in any other tool for this API.

Multi-device control

bulk — Power, mode, or speed across every device matching a type/room filter in one command.

Replaces the #1 user pain — tapping each device in the Dreo app at bedtime — with one cron-callable line.
```
dreo-pp-cli bulk --action off --type tower-fan --dry-run
```
scene save — Capture the current state across selected devices as a named scene and replay it later as parallel WebSocket frames.

Sam's nightly bedtime routine becomes one command; survives app updates.
```
dreo-pp-cli scene save bedtime --all && dreo-pp-cli scene apply bedtime --dry-run
```

Cross-device intelligence

sensors — Aggregated temperature, humidity, and PM2.5 across every sensor-bearing device in one ranked table.

Answers the agent question 'what's the air quality across my house?' in one tool call.
```
dreo-pp-cli sensors --json
```
sensors record — Persist WebSocket state events to a local sensor_readings table and query temperature/humidity/PM2.5 over arbitrary time windows.

Answers 'when did the bedroom fan last go to sleep mode' and similar historical questions agents and users actually ask.
```
dreo-pp-cli sensors query --metric temperature --since 1h --json
```
alerts — Report devices with low filter life, empty water tank, offline heartbeat, or sensor readings past a threshold.

Surfaces actionable problems (filter, water, dead devices) without manually inspecting each device.
```
dreo-pp-cli alerts --pm25-above 50 --json
```
rooms — Group devices by room with on-count, average temperature, and average humidity per room.

Answers 'what's happening in my bedroom right now' in one query.
```
dreo-pp-cli rooms --json
```
devices search — Full-text search over cached device name, room, model, and serial.

Fast device lookup for scripts and agents without round-tripping the cloud.
```
dreo-pp-cli devices search Fan
```

Realtime observability

watch — Tail-f for Dreo device state — every WebSocket update as a JSON line on stdout.

Enables automation debugging without running Home Assistant, and feeds agent stream-processing pipelines.
```
dreo-pp-cli watch --all --json
```

Usage

Run dreo-pp-cli --help for the full command reference and flag list.

Commands

devices

Discover and inspect Dreo devices on your account

dreo-pp-cli devices list - List every Dreo device on your account
dreo-pp-cli devices state - Read the current state snapshot for one device

firmware

Read firmware metadata and check for updates

dreo-pp-cli firmware - Check whether a firmware update is available for a device

settings

Read and write persistent per-device settings

dreo-pp-cli settings get - Get persistent settings for a device
dreo-pp-cli settings update - Update persistent settings for a device

Output Formats

# Human-readable table (default in terminal, JSON when piped)
dreo-pp-cli devices list

# JSON for scripting and agents
dreo-pp-cli devices list --json

# Filter to specific fields
dreo-pp-cli devices list --json --select id,name,status

# Dry run — show the request without sending
dreo-pp-cli devices list --dry-run

# Agent mode — JSON + compact + no prompts in one flag
dreo-pp-cli devices list --agent

Agent Usage

This CLI is designed for AI agent consumption:

Non-interactive - never prompts, every input is a flag
Pipeable - --json output to stdout, errors to stderr
Filterable - --select id,name returns only fields you need
Previewable - --dry-run shows the request without sending
Explicit retries - add --idempotent to create retries when a no-op success is acceptable
Confirmable - --yes for explicit confirmation of destructive actions
Piped input - write commands can accept structured input when their help lists --stdin
Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

dreo-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/dreo-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
`DREO_USERNAME`	per_call	Yes	Set to your API credential.
`DREO_PASSWORD`	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

Run dreo-pp-cli doctor to check credentials
Verify the environment variable is set: echo $DREO_USERNAME Not found errors (exit code 3)
Check the resource ID is correct
Run the list command to see available items

API-specific

doctor reports auth failure — Verify DREO_USERNAME and DREO_PASSWORD are exported; if you changed your password in the Dreo app, run dreo-pp-cli auth login again
Empty device list — Run dreo-pp-cli devices list --live to bypass the local cache and fetch fresh from the cloud
Commands return but device state does not change — Add --wait to the set/bulk command so the CLI confirms the WebSocket state echo before exiting
Wrong region — Set DREO_REGION=eu (or us) to skip the region-discovery round-trip; the CLI auto-detects on first login

Sources & Inspiration

This CLI was built by studying these projects and resources:

hass-dreo — Python (200 stars)
homebridge-dreo — TypeScript (80 stars)
hass-dreoverse — Python (30 stars)
pydreo-client — Python (20 stars)

Generated by CLI Printing Press