@switchbot/openapi-cli

npm version npm downloads license node CI

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 · RGBICWW Ceiling Light · RGBIC Neon Rope Light · RGBIC Neon Wire Rope Light · Candle Warmer Lamp · Permanent Outdoor Lights
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 · Battery Circulator Fan 2 Pro · 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 · AI MindClip · Kata Friends · 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/openapi-cli @switchbot/codex-plugin
switchbot codex setup # one-shot bootstrap: register, auth, verify

Or install via Codex Plugin Marketplace (requires Codex CLI with marketplace support):

codex plugin marketplace add OpenWonderLabs/switchbot-openapi-cli
codex plugin add switchbot@switchbot
switchbot auth login

Claude Code integration

Already configured? Paste into Claude Code chat:

Is my SwitchBot integration working? Please check and list my devices.

Claude will call account_overview or switchbot doctor to verify — no terminal needed.

Fresh setup — paste into Claude Code chat:

Please set up my SwitchBot integration by running:
npx @switchbot/openapi-cli claude-code setup

Claude will run the setup command via the Bash tool. It installs the CLI if missing, registers the MCP server via claude mcp add --scope user, and opens a browser login if credentials are not yet configured. Restart Claude Code afterwards to load the MCP tools.

Or run manually in your terminal:

npm install -g @switchbot/openapi-cli
switchbot claude-code setup

The optional skill package @switchbot/claude-code-plugin bundles the SKILL.md context document. Install it only if your environment does not already load the skill automatically.

Or install via Claude Code Plugin Marketplace (requires Claude Code with plugin marketplace support enabled):

/plugin marketplace add OpenWonderLabs/switchbot-openapi-cli
/plugin install switchbot@switchbot

Note: The root marketplace.json in this repo is for Codex CLI Route B (git sparse clone) and points to packages/codex-plugin/plugins/switchbot. The .claude-plugin/marketplace.json is for Claude Code Plugin Marketplace and points to packages/claude-code-plugin/plugins/switchbot.

Gemini CLI integration

The Gemini extension is in packages/gemini-extension/ — it provides up to 28 MCP tools (14 readonly, 17 default, 28 with --tools all; see docs/agent-guide.md for the deprecated-aliases breakdown), a GEMINI.md context file, and 23 slash commands.

Recommended — paste into Gemini CLI chat:

Please set up the SwitchBot integration for me by running:
npx @switchbot/openapi-cli gemini setup
Then restart Gemini CLI and confirm it's working by listing my devices.

gemini setup installs or upgrades the CLI, registers the MCP server in ~/.gemini/settings.json, and opens a browser login page to save credentials to the OS keychain — no token copy-paste needed.

Or install the full extension (adds 23 slash commands + GEMINI.md context):

npm install -g @switchbot/openapi-cli
git clone https://github.com/OpenWonderLabs/switchbot-openapi-cli.git
gemini extensions link ./switchbot-openapi-cli/packages/gemini-extension

Gemini CLI prompts for SWITCHBOT_TOKEN and SWITCHBOT_SECRET during install (stored securely in system keychain).

Or run MCP-only setup directly in your terminal:

npm install -g @switchbot/openapi-cli
switchbot gemini setup

Verify:

switchbot gemini doctor

After setup, restart Gemini CLI and ask: "List my SwitchBot devices."

OpenClaw integration

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

Paste into OpenClaw chat:

Please set up the SwitchBot integration for me by running:
npx @switchbot/openapi-cli install --agent openclaw
Then confirm it's working by listing my devices.

Or install directly:

npm install -g @switchbot/openapi-cli
openclaw plugins install @switchbot/openclaw-skill
switchbot auth login

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

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>

`mindclip`

switchbot mindclip recordings [--device <id>] [--page <n>] [--size <n>]
switchbot mindclip recording <id> [--language en|zh]
switchbot mindclip summary <id>
switchbot mindclip todos [--completed 0|1|2] [--category 0..5]
switchbot mindclip daily [--date YYYY-MM-DD]
switchbot mindclip weekly [--week YYYY-Www]
switchbot mindclip urgent-todos [--date YYYY-MM-DD]

`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

`gemini`

switchbot gemini setup [--yes] [--dry-run] [--json] # register MCP in ~/.gemini/settings.json
switchbot gemini doctor [--quiet] [--json] # check CLI + MCP + credentials health

`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 — default 17 tools (use --tools all for 28)

`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

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

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.githooks		.githooks
.github/workflows		.github/workflows
docs		docs
examples		examples
packages		packages
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.jsonc		.markdownlint.jsonc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
TESTING.md		TESTING.md
docker-compose.example.yml		docker-compose.example.yml
marketplace.json		marketplace.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

@switchbot/openapi-cli

Installation

Supported devices

Quick start

Codex integration

Claude Code integration

Gemini CLI integration

OpenClaw integration

Credentials

Commands

devices

scenes

mindclip

codex

gemini

auth

config

mcp

webhook

events

status-sync

rules / daemon

plan

policy

doctor / health

Other

Global options

Exit codes

Environment variables

Development

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages