@switchbot/openapi-cli

@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.

• npm: @switchbot/openapi-cli
• Source / issues: github.com/OpenWonderLabs/switchbot-openapi-cli
• Releases / changelog: GitHub Releases

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.

codex setup installs or upgrades the CLI and plugin packages, registers the plugin with Codex, and opens a browser login page to save credentials to the OS keychain — no token copy-paste needed.

Or install directly:

npm install -g @switchbot/codex-plugin
switchbot-codex-install        # registers the plugin with Codex
switchbot auth login           # browser OAuth — saves to OS keychain

OpenClaw integration

The OpenClaw skill is published to npm as @switchbot/openclaw-skill.

openclaw plugins install @switchbot/openclaw-skill   # via OpenClaw plugin manager (recommended)
# or
npm install -g @switchbot/openclaw-skill             # via npm

switchbot-openclaw setup   # verify CLI install and credentials
switchbot auth login       # browser OAuth — saves to OS keychain

switchbot-openclaw setup verifies @switchbot/openapi-cli is installed at >=3.7.1 and authenticated. Safe to re-run.

Claude Code integration

The Claude Code plugin is published to npm as @switchbot/claude-code-plugin.

Recommended — paste into Claude Code chat:

Please set up the SwitchBot integration for me by running:
npm install -g @switchbot/claude-code-plugin
claude plugins add @switchbot/claude-code-plugin
Then restart Claude Code and confirm it's working.

Or install directly:

npm install -g @switchbot/claude-code-plugin
claude plugins add @switchbot/claude-code-plugin   # registers the MCP server and skill
switchbot auth login                                # browser OAuth — saves to OS keychain

claude plugins add runs the onInstall hook automatically. If SwitchBot credentials are not yet configured, a browser login window opens. Run switchbot-claude-auth at any time to re-authenticate.

Note: The root marketplace.json file in this repo is for Codex CLI Route B (git sparse clone) and points to the Codex plugin at packages/codex-plugin/plugins/switchbot. Claude Code users install via npm and do not use this file.

Credentials

Recommended: use switchbot auth login for browser-based OAuth — credentials are stored securely in the OS keychain and never need to be copy-pasted anywhere.

Priority: env vars → OS keychain → ~/.switchbot/config.json

switchbot auth login                             # browser OAuth — opens login page, saves to OS keychain
switchbot config set-token <token> <secret>     # manual setup (alternative)
export SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=... # CI / env override
switchbot auth keychain set/get/delete          # OS keychain management

Commands

devices

switchbot 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"

scenes

switchbot scenes list
switchbot scenes execute <sceneId>

codex

switchbot 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

auth

switchbot auth login [--no-open] [--timeout 60]
switchbot auth keychain describe/set/get/migrate/delete

config

switchbot config set-token <token> <secret>
switchbot config show
switchbot config list-profiles

mcp

switchbot mcp serve    # stdio MCP server — 24 tools

webhook

switchbot webhook setup <url>
switchbot webhook query [--details <url>]
switchbot webhook update <url> --enable/--disable
switchbot webhook delete <url>

events

switchbot events tail [--filter deviceId=X] [--port 8080]
switchbot events mqtt-tail [--max 10] [--for 30s] [--json]

status-sync

switchbot status-sync start --openclaw-model home-agent
switchbot status-sync status --json
switchbot status-sync stop

rules / daemon

Policy-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

plan

Declarative 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

policy

switchbot policy new/validate/migrate/backup/restore

doctor / health

switchbot doctor [--json] [--fix --yes]
switchbot health check [--json] [--prometheus]
switchbot health serve [--port 3100]

Other

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

Global options

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

Exit codes

Code	Meaning
0	Success
1	Runtime error (API / network / credentials)
2	Usage error (bad flag / unknown command / validation)

Environment variables

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)

Development

npm install && npm run build
npm run dev -- <args>   # run from TypeScript via tsx
npm test                # Vitest suite

License

MIT © chenliuyun

• SwitchBot API v1.1 · Base URL: https://api.switch-bot.com · Rate limit: 10,000 req/day