@switchbot/openapi-cli
SwitchBot smart home CLI — control devices, run scenes, stream events, and plug AI agents into your home via the built-in MCP server.
Human — start with Quick start: colored tables, error hints, shell completion, switchbot doctor.
Script — start with Global options: --json, --format tsv/yaml/id, --fields, stable exit codes, audit log.
Agent — start with docs/agent-guide.md: mcp serve, schema export, plan run, destructive-command guards.
Every surface shares the same catalog, cache, and HMAC client.
Installation
npm install -g @switchbot/openapi-cli
Requires Node.js ≥ 18. Run switchbot auth login to authenticate via browser — no Developer Options needed.
To use API token/secret directly instead, first obtain your credentials from the SwitchBot app:
- Open the SwitchBot app → tap your profile avatar (top-right)
- Go to Preferences → App Version, tap the version number 10 times to unlock Developer Options
- Return to Preferences → Developer Options
- Copy your Token and Secret Key
Then run:
switchbot config set-token <token> <secret>
Supported devices
Run switchbot catalog list to see the full list including aliases and per-command details.
| Category | Devices |
|---|
| Lighting | Color Bulb · Strip Light · Strip Light 3 · RGBICWW Strip Light · Floor Lamp · RGBICWW Floor Lamp · Ceiling Light · Ceiling Light Pro · RGBIC Neon Rope Light · RGBIC Neon Wire Rope Light · Candle Warmer Lamp |
| Climate | Humidifier · Humidifier2 · Air Purifier VOC · Air Purifier Table VOC · Air Purifier PM2.5 · Air Purifier Table PM2.5 · Smart Radiator Thermostat |
| Security | Smart Lock · Smart Lock Pro · Smart Lock Pro Wifi · Smart Lock Ultra · Lock Lite · Lock Vision · Lock Vision Pro · Keypad · Keypad Touch · Keypad Vision · Keypad Vision Pro · Garage Door Opener · Video Doorbell |
| Curtains & blinds | Curtain · Curtain3 · Blind Tilt · Roller Shade |
| Power | Plug · Plug Mini (US) · Plug Mini (JP) · Plug Mini (EU) · Relay Switch 1 · Relay Switch 1PM · Relay Switch 2PM |
| Fans | Battery Circulator Fan · Circulator Fan · Standing Circulator Fan |
| Cleaning | Robot Vacuum Cleaner S1 · Robot Vacuum Cleaner S1 Plus · K10+ · K10+ Pro · Robot Vacuum Cleaner K10+ Pro Combo · Robot Vacuum Cleaner S10 · Robot Vacuum Cleaner S20 · Robot Vacuum Cleaner K11+ · Robot Vacuum Cleaner K20 Plus Pro |
| Sensors (read-only) | Meter · MeterPlus · WoIOSensor · MeterPro · MeterPro(CO2) · WeatherStation · Motion Sensor · Presence Sensor · Contact Sensor · Water Detector · Wallet Finder Card |
| Hubs (read-only) | Hub · Hub Plus · Hub Mini · Hub 2 · Hub 3 · AI Hub |
| Cameras (status only) | Indoor Cam · Pan/Tilt Cam · Pan/Tilt Cam 2K · Pan/Tilt Cam Plus 2K · Pan/Tilt Cam Plus 3K · Outdoor Spotlight Cam |
| Other | Bot · AI Art Frame · Home Climate Panel · Remote |
| IR virtual remotes (via Hub) | Air Conditioner · TV · Streamer · Set Top Box · DVD · Speaker · Fan · Light · Others |
Quick start
switchbot auth login # browser OAuth — saves to OS keychain
switchbot config set-token <token> <secret> # or set credentials manually
switchbot devices list # list all devices
switchbot devices command <id> turnOn
switchbot doctor # self-check
Codex integration
The Codex plugin is published to npm as @switchbot/codex-plugin.
Recommended — paste into Codex chat:
Please set up the SwitchBot integration for me by running:
npx @switchbot/openapi-cli codex setup
Then restart Codex and confirm it's working.
