---
name: switchbot-read
description: Read-only SwitchBot Cloud discovery via the local reference CLI (tmp/reference/switchbot-control-reference) — list devices/infrared remotes and inspect a device's documented command interface. Never sends control commands and never touches .env.
---

# SwitchBot Read-Only Discovery

Use this whenever you need to find a SwitchBot device ID, confirm a device's
type, or see which commands are documented for it — e.g. resolving "the
Dyson" or "the AC" to an exact `deviceId` before building or running any
control call in `ha-gateway`'s `RemoteService`.

This wraps `tmp/reference/switchbot-control-reference/scripts/switchbot-read`,
a wrapper that only accepts `list` and `interface` — it has no code path that
can send a device command, so it's safe to run freely.

## Why `GOWORK=off` is required

This reference tool is nested inside the `home-service` repo but is its own
Go module, not a member of the root `go.work`. Running it from inside the
workspace fails with "directory prefix . does not contain modules listed in
go.work" unless you disable workspace mode for that one subprocess:

```bash
cd tmp/reference/switchbot-control-reference
GOWORK=off ./scripts/switchbot-read list all
```

Do not add this tool to the root `go.work` — that file is committed, `tmp/`
is gitignored, and pointing a committed file at a gitignored path would break
every other clone of this repo.

## Commands

```bash
GOWORK=off ./scripts/switchbot-read list all
GOWORK=off ./scripts/switchbot-read list physical
GOWORK=off ./scripts/switchbot-read list remotes    # infrared/virtual remotes — Dyson, AC live here
GOWORK=off ./scripts/switchbot-read list switches
GOWORK=off ./scripts/switchbot-read list locks
GOWORK=off ./scripts/switchbot-read interface DEVICE_ID
```

Output is JSON: `{filter, count, devices: [...]}` for `list`, or a single
`deviceView` object for `interface`. Each device includes a `commands` array
of documented `{name, parameter, commandType, description}` entries derived
from the device's type — this is a **static catalog**, not something
dynamically read from the appliance, and it does not include learned custom
IR button names (SwitchBot's API has no endpoint for that — see
`CustomButtonNamesDiscoverable: false` on infrared entries).

## Rules

1. Never read, print, or expose `tmp/reference/switchbot-control-reference/.env`
   yourself — the CLI reads it internally via `os.Getenv`, you never need to.
   (A project hook already blocks `Read`/`Edit`/`Write` on real `.env` files
   and Bash commands referencing them, but don't rely on the hook — just
   don't try.)
2. This skill is discovery-only. If you need to send a command, use the
   `switchbot-control` skill instead — never shell out to `switchbotctl`
   (the full CLI) from here.
3. Treat `commands` in the output as "what SwitchBot's documented API
   supports for this device type," not confirmation the physical appliance
   will respond correctly to every listed command — some DIY/customized
   remotes reject a documented standard command with error 160.