@switchbot/openapi-cli
Advanced tools
SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.
SwitchBot smart home CLI — control devices, run scenes, stream events, and plug AI agents into your home via the built-in MCP server.
@switchbot/openapi-cliHuman — 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.
npm install -g @switchbot/openapi-cli
Requires Node.js ≥ 18 and a SwitchBot account with Developer Options enabled.
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 |
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
The Codex plugin is self-hosted in this repo (packages/codex-plugin/) — no separate npm package required.
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.
Or run directly (if CLI is already installed):
codex plugin marketplace add OpenWonderLabs/switchbot-openapi-cli \
--sparse packages/codex-plugin --ref main
codex plugin add switchbot@codex-plugin
switchbot auth login
Priority: env vars → OS keychain → ~/.switchbot/config.json
switchbot auth login # browser OAuth (recommended)
switchbot config set-token <t> <s> # manual setup
export SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=... # CI / env override
switchbot auth keychain set/get/delete # OS keychain management
devicesswitchbot devices list [--wide] [--filter 'type=Bot'] [--json]
switchbot devices status <id> [--ids A,B,C]
switchbot devices command <id> <cmd> [parameter]
switchbot devices expand <id> setAll --temp 26 --mode cool # named flags for packed params
switchbot devices watch <id> [--interval 10s] [--for 5m]
switchbot devices batch turnOff --filter 'type=Bot'
switchbot devices meta set <id> --alias "Office Light"
scenesswitchbot scenes list
switchbot scenes execute <sceneId>
codexswitchbot codex setup [--yes] [--dry-run] [--json] # full bootstrap
switchbot codex doctor [--quiet] [--json] # 7-check health summary
switchbot codex repair [--skip re-auth] [--yes] # re-register + re-verify
authswitchbot auth login [--no-open] [--timeout 60]
switchbot auth keychain describe/set/get/migrate/delete
configswitchbot config set-token <token> <secret>
switchbot config show
switchbot config list-profiles
mcpswitchbot mcp serve # stdio MCP server — 24 tools
webhookswitchbot webhook setup <url>
switchbot webhook query [--details <url>]
switchbot webhook update <url> --enable/--disable
switchbot webhook delete <url>
eventsswitchbot events tail [--filter deviceId=X] [--port 8080]
switchbot events mqtt-tail [--max 10] [--for 30s] [--json]
status-syncswitchbot status-sync start --openclaw-model home-agent
switchbot status-sync status --json
switchbot status-sync stop
rules / daemonPolicy-driven automations. Triggers: mqtt · cron · webhook. Conditions: time_between · device_state · event_count · llm. Actions: command · notify.
switchbot rules lint
switchbot rules list/explain/run/simulate
switchbot rules tail/replay/summary/conflicts/doctor
switchbot rules suggest --intent "turn off AC at 11pm" [--llm auto]
switchbot daemon start/stop/reload/status
planDeclarative batch operations. A plan file has version, description, and a steps array.
switchbot plan schema/suggest/validate
switchbot plan run plan.json [--dry-run] [--require-approval]
switchbot plan save/review/approve/execute
policyswitchbot policy new/validate/migrate/backup/restore
doctor / healthswitchbot doctor [--json] [--fix --yes]
switchbot health check [--json] [--prometheus]
switchbot health serve [--port 3100]
switchbot history show [--limit 20]
switchbot quota status/reset
switchbot upgrade-check [--json]
switchbot catalog show/search
switchbot schema export [--type 'Strip Light']
switchbot capabilities --json
switchbot cache show/clear
switchbot reset [--yes] [--keep-credentials]
switchbot completion bash/zsh/fish/powershell
| Flag | Description |
|---|---|
--json | Raw JSON output |
--format <fmt> | tsv / yaml / jsonl / id |
--fields <cols> | Comma-separated column filter |
--dry-run | Preview mutating requests without sending |
--verbose | Log HTTP request/response to stderr |
--timeout <ms> | HTTP timeout (default 30000) |
--config <path> | Override credential file location |
--profile <name> | Named credential profile |
--cache <dur> | Cache TTL (5m, 1h, off, auto) |
--no-cache | Disable all cache reads |
--retry-on-429 <n> | Max 429 retry attempts (default 3) |
--audit-log | Append mutating commands to audit log |
| Code | Meaning |
|---|---|
0 | Success |
1 | Runtime error (API / network / credentials) |
2 | Usage error (bad flag / unknown command / validation) |
| Variable | Description |
|---|---|
SWITCHBOT_TOKEN | API token (overrides config file) |
SWITCHBOT_SECRET | API secret (overrides config file) |
NO_COLOR | Disable ANSI colors |
CODEX_GIT_MARKETPLACE_REF | Git ref used when registering the Codex plugin via the git marketplace (default: main) |
npm install && npm run build
npm run dev -- <args> # run from TypeScript via tsx
npm test # Vitest suite
MIT © chenliuyun
https://api.switch-bot.com · Rate limit: 10,000 req/dayFAQs
SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.
The npm package @switchbot/openapi-cli receives a total of 45 weekly downloads. As such, @switchbot/openapi-cli popularity was classified as not popular.
We found that @switchbot/openapi-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Five frontier LLMs generated the same nonexistent package names, leaving 53 available for potential slopsquatting across PyPI and npm.
Security News
The White House’s Gold Eagle Initiative aims to coordinate AI-discovered vulnerabilities, validate findings, and accelerate patching across critical software.
Security News
A Shai-Hulud infection exposed Suno's source code, which shows the AI music startup stream-ripped tracks to train its models.