pp-dreo

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/devices/dreo/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Dreo — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `dreo-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install dreo --cli-only
   ```
2. Verify: `dreo-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/devices/dreo/cmd/dreo-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI whenever an agent or script needs to read or control Dreo devices without Home Assistant in the loop. It is ideal for one-shot bulk commands (turn everything off at bedtime), whole-house sensor reads, live state streaming for automation debugging, and any cron-driven Dreo automation. The agent-callable MCP surface mirrors every Cobra command so AI agents can drive your home without a custom integration.

## Unique Capabilities

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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  dreo-pp-cli watch --all --json
  ```

## Command Reference

**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


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
dreo-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Hand-written Extensions

These commands are declared by the spec author and require separate hand-written wiring; the generator does not emit Cobra registration for them. They are listed here for discoverability and are intentionally outside `## Command Reference` so the verify-skill unknown-command check does not treat them as generator-owned paths.

- `dreo-pp-cli set <device>` — Set state on a device (power, speed, mode, oscillation, timer) over WebSocket
- `dreo-pp-cli bulk` — Fan-out a control command across every device matching a filter (--type, --room)
- `dreo-pp-cli watch` — Tail-f for Dreo device state — every WebSocket update as a JSON line on stdout
- `dreo-pp-cli sensors` — Whole-house temperature, humidity, and PM2.5 across every sensor-bearing device
- `dreo-pp-cli sensors record` — Record WebSocket state events to a local sensor_readings table for timeseries history
- `dreo-pp-cli sensors query` — Query the local sensor_readings table over arbitrary time windows
- `dreo-pp-cli alerts` — Report devices with low filter life, empty water tank, offline heartbeat, or sensor thresholds
- `dreo-pp-cli scene save <name>` — Snapshot the current state across selected devices as a named scene
- `dreo-pp-cli scene apply <name>` — Replay a saved scene as parallel WebSocket control frames
- `dreo-pp-cli rooms` — Per-room aggregates (device count, on-count, avg temperature, avg humidity)
- `dreo-pp-cli auth login` — Exchange Dreo email and password for an access token; caches token for subsequent calls
- `dreo-pp-cli auth logout` — Clear cached Dreo access token from local config
- `dreo-pp-cli auth status` — Show current Dreo auth status (cached token age, region, last login)

## Recipes


### Bedtime bulk-off

```bash
dreo-pp-cli bulk --action off --type tower-fan && dreo-pp-cli bulk --action sleep --type air-purifier
```

One line replaces ten taps in the Dreo app; cron-friendly.

### Whole-house sensor read (agent-friendly with --select)

```bash
dreo-pp-cli sensors --json --select 'devices.name,devices.room,devices.temperature_c,devices.humidity,devices.pm25'
```

Returns only the sensor columns an agent needs, dropping the verbose device metadata.

### Capture a bedtime scene

```bash
dreo-pp-cli scene save bedtime --all && dreo-pp-cli scene apply bedtime --dry-run
```

Snapshot all device state under a named scene, then replay it any night.

### Filter and water-tank alert sweep

```bash
dreo-pp-cli alerts --json
```

Reports purifiers with filter life < 10% and humidifiers with empty water tanks across your whole account.

### Sensor history query

```bash
dreo-pp-cli sensors query --device Fan --metric temperature --since 24h --json
```

Run the recorder in the background, then