---
name: switchbot-control
description: Gated SwitchBot Cloud device control via the local reference CLI (tmp/reference/switchbot-control-reference) — turn-on/off, fan/AC/lock commands, and custom IR buttons. Always resolves and inspects the target first, always dry-runs before a real send, always requires explicit user approval before executing.
---

# SwitchBot Control (gated)

This wraps `tmp/reference/switchbot-control-reference/scripts/switchbotctl`,
the full control CLI. Every real control call fires a real signal at real
hardware (an actual IR blast, an actual lock toggle) — treat every non-dry-run
invocation as something you are asking permission to do, not something you
just do.

## Required sequence, every time

1. **Resolve the device.** Use the `switchbot-read` skill (`list all` /
   `list remotes` / `list switches` / `list locks`) to find the exact
   `deviceId` for the device the user named. Never guess an ID or reuse one
   from memory without re-confirming it still matches — if more than one
   device could match the name, ask which one; never pick one silently.
2. **Inspect the interface.** Run `switchbot-read interface DEVICE_ID` and
   confirm the command you're about to send is actually in its documented
   `commands` list (or, for a custom button, that the device is an infrared
   remote where `customize`-type commands apply).
3. **Dry-run first.** Always construct and check the exact call with
   `--dry-run` before ever running it for real:
   ```bash
   cd tmp/reference/switchbot-control-reference
   GOWORK=off ./scripts/switchbotctl ac DEVICE_ID 24 cool medium on --dry-run
   ```
   Confirm the echoed `command`/`parameter`/`commandType` in the dry-run
   output is exactly what you intend.
4. **Ask for explicit approval** before running the same command without
   `--dry-run`. State the exact device (name + ID) and the exact action in
   plain language. Do not treat a general "go ahead with the plan" from
   earlier in the conversation as approval for a specific real control call —
   ask again, per command, right before running it.
5. **Execute once.** Run the approved command exactly once. Do not retry
   automatically on failure or on an ambiguous result — a repeated lock,
   toggle, Bot press, or custom IR command can produce a real second action
   (e.g. re-toggling something back off). If it needs retrying, ask first.
6. **Treat success as API acceptance, not physical confirmation.** SwitchBot
   Cloud's infrared control is fire-and-forget — a `200`/`statusCode: 100`
   response means the cloud accepted the command, not that the appliance
   actually received or acted on the IR signal.

## Custom IR buttons (`button`) need the user, not a guess

```bash
GOWORK=off ./scripts/switchbotctl button DEVICE_ID "Exact Button Name" --dry-run
```

SwitchBot's API cannot enumerate a device's learned custom button names —
they only exist as case-sensitive labels in the SwitchBot app. Never
approximate, guess, or case-fold a button name. If you don't have the exact
label from the user, stop and ask for it rather than trying a plausible
guess.

## Command reference (see `tmp/reference/switchbot-control-reference/README.md` for the full list)

```bash
switchbotctl turn-on DEVICE_ID [--dry-run]
switchbotctl turn-off DEVICE_ID [--dry-run]
switchbotctl press DEVICE_ID [--dry-run]
switchbotctl lock DEVICE_ID [--dry-run]
switchbotctl unlock DEVICE_ID [--dry-run]
switchbotctl fan DEVICE_ID swing|timer|lowSpeed|middleSpeed|highSpeed [--dry-run]
switchbotctl ac DEVICE_ID TEMPERATURE MODE FAN_SPEED POWER [--dry-run]
switchbotctl button DEVICE_ID "Exact Button Name" [--dry-run]
switchbotctl send DEVICE_ID COMMAND PARAMETER COMMAND_TYPE [--dry-run]   # generic escape hatch
```

Always run from `tmp/reference/switchbot-control-reference/` with
`GOWORK=off` prefixed (this repo's root `go.work` doesn't include this nested
module — see the `switchbot-read` skill for why not to fix that by editing
`go.work`).

## Hard rules

- Never read, print, edit, source, or expose `.env` in this directory.
- Never add an automatic hook, cron, or script that calls `switchbotctl`
  without a human in the loop for that specific invocation.
- This CLI is a **development/testing aid only** — it is not a dependency of
  `ha-gateway`. The actual `RemoteService` implementation in `ha-gateway` has
  its own hand-rolled SwitchBot HTTP client (see `plan.md`); use this CLI to
  discover device IDs and verify command behavior during development, not as
  something the running services call at runtime.