nik/home-services
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
home-services/.claude/skills/switchbot-read/SKILL.md

3.0 KiB
Raw Blame History

name, description
name description
switchbot-read 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:

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

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.