{"id":48943612,"url":"https://github.com/openwonderlabs/switchbot-openapi-cli","last_synced_at":"2026-05-24T10:02:38.741Z","repository":{"id":352019013,"uuid":"1213447359","full_name":"OpenWonderLabs/switchbot-openapi-cli","owner":"OpenWonderLabs","description":"Command-line interface for the SwitchBot API v1.1","archived":false,"fork":false,"pushed_at":"2026-05-21T04:30:41.000Z","size":1586,"stargazers_count":110,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-21T11:07:10.312Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenWonderLabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T11:45:52.000Z","updated_at":"2026-05-20T02:08:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"b8962af6-6ca5-419e-8b32-5387910104af","html_url":"https://github.com/OpenWonderLabs/switchbot-openapi-cli","commit_stats":null,"previous_names":["openwonderlabs/switchbot-openapi-cli"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/OpenWonderLabs/switchbot-openapi-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fswitchbot-openapi-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fswitchbot-openapi-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fswitchbot-openapi-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fswitchbot-openapi-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenWonderLabs","download_url":"https://codeload.github.com/OpenWonderLabs/switchbot-openapi-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenWonderLabs%2Fswitchbot-openapi-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33429192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-17T15:00:57.279Z","updated_at":"2026-05-24T10:02:38.722Z","avatar_url":"https://github.com/OpenWonderLabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @switchbot/openapi-cli\n\n[![npm version](https://img.shields.io/npm/v/@switchbot/openapi-cli.svg)](https://www.npmjs.com/package/@switchbot/openapi-cli)\n[![npm downloads](https://img.shields.io/npm/dm/@switchbot/openapi-cli.svg)](https://www.npmjs.com/package/@switchbot/openapi-cli)\n[![license](https://img.shields.io/npm/l/@switchbot/openapi-cli.svg)](./LICENSE)\n[![node](https://img.shields.io/node/v/@switchbot/openapi-cli.svg)](https://nodejs.org)\n[![CI](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml)\n\nSwitchBot smart home CLI — control devices, run scenes, stream events, and plug AI agents into your home via the built-in MCP server.\n\n- **npm:** [`@switchbot/openapi-cli`](https://www.npmjs.com/package/@switchbot/openapi-cli)\n- **Source / issues:** [github.com/OpenWonderLabs/switchbot-openapi-cli](https://github.com/OpenWonderLabs/switchbot-openapi-cli)\n- **Releases / changelog:** [GitHub Releases](https://github.com/OpenWonderLabs/switchbot-openapi-cli/releases)\n\n---\n\n**Human** — start with [Quick start](#quick-start): colored tables, error hints, shell completion, `switchbot doctor`.  \n**Script** — start with [Global options](#global-options): `--json`, `--format tsv/yaml/id`, `--fields`, stable exit codes, audit log.  \n**Agent** — start with [`docs/agent-guide.md`](./docs/agent-guide.md): `mcp serve`, `schema export`, `plan run`, destructive-command guards.\n\nEvery surface shares the same catalog, cache, and HMAC client.\n\n---\n\n## Installation\n\n```bash\nnpm install -g @switchbot/openapi-cli\n```\n\nRequires Node.js ≥ 18 and a SwitchBot account with **Developer Options** enabled.\n\n---\n\n## Supported devices\n\nRun `switchbot catalog list` to see the full list including aliases and per-command details.\n\n| Category | Devices |\n|---|---|\n| **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 |\n| **Climate** | Humidifier · Humidifier2 · Air Purifier VOC · Air Purifier Table VOC · Air Purifier PM2.5 · Air Purifier Table PM2.5 · Smart Radiator Thermostat |\n| **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 |\n| **Curtains \u0026 blinds** | Curtain · Curtain3 · Blind Tilt · Roller Shade |\n| **Power** | Plug · Plug Mini (US) · Plug Mini (JP) · Plug Mini (EU) · Relay Switch 1 · Relay Switch 1PM · Relay Switch 2PM |\n| **Fans** | Battery Circulator Fan · Circulator Fan · Standing Circulator Fan |\n| **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 |\n| **Sensors** _(read-only)_ | Meter · MeterPlus · WoIOSensor · MeterPro · MeterPro(CO2) · WeatherStation · Motion Sensor · Presence Sensor · Contact Sensor · Water Detector · Wallet Finder Card |\n| **Hubs** _(read-only)_ | Hub · Hub Plus · Hub Mini · Hub 2 · Hub 3 · AI Hub |\n| **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 |\n| **Other** | Bot · AI Art Frame · Home Climate Panel · Remote |\n| **IR virtual remotes** _(via Hub)_ | Air Conditioner · TV · Streamer · Set Top Box · DVD · Speaker · Fan · Light · Others |\n\n---\n\n## Quick start\n\n```bash\nswitchbot auth login                        # browser OAuth — saves to OS keychain\nswitchbot config set-token \u003ctoken\u003e \u003csecret\u003e # or set credentials manually\nswitchbot devices list                      # list all devices\nswitchbot devices command \u003cid\u003e turnOn\nswitchbot doctor                            # self-check\n```\n\n---\n\n## Codex integration\n\nThe Codex plugin is self-hosted in this repo (`packages/codex-plugin/`) — no separate npm package required.\n\n**Paste into Codex chat:**\n\n```\nPlease set up the SwitchBot integration for me by running:\nnpx @switchbot/openapi-cli codex setup\nThen restart Codex and confirm it's working.\n```\n\n**Or run directly (if CLI is already installed):**\n\n```bash\ncodex plugin marketplace add OpenWonderLabs/switchbot-openapi-cli \\\n  --sparse packages/codex-plugin --ref main\ncodex plugin add switchbot@codex-plugin\nswitchbot auth login\n```\n\n---\n\n## Credentials\n\nPriority: env vars → OS keychain → `~/.switchbot/config.json`\n\n```bash\nswitchbot auth login                   # browser OAuth (recommended)\nswitchbot config set-token \u003ct\u003e \u003cs\u003e    # manual setup\nexport SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=...   # CI / env override\nswitchbot auth keychain set/get/delete # OS keychain management\n```\n\n---\n\n## Commands\n\n### `devices`\n\n```bash\nswitchbot devices list [--wide] [--filter 'type=Bot'] [--json]\nswitchbot devices status \u003cid\u003e [--ids A,B,C]\nswitchbot devices command \u003cid\u003e \u003ccmd\u003e [parameter]\nswitchbot devices expand \u003cid\u003e setAll --temp 26 --mode cool  # named flags for packed params\nswitchbot devices watch \u003cid\u003e [--interval 10s] [--for 5m]\nswitchbot devices batch turnOff --filter 'type=Bot'\nswitchbot devices meta set \u003cid\u003e --alias \"Office Light\"\n```\n\n### `scenes`\n\n```bash\nswitchbot scenes list\nswitchbot scenes execute \u003csceneId\u003e\n```\n\n### `codex`\n\n```bash\nswitchbot codex setup [--yes] [--dry-run] [--json]   # full bootstrap\nswitchbot codex doctor [--quiet] [--json]             # 7-check health summary\nswitchbot codex repair [--skip re-auth] [--yes]       # re-register + re-verify\n```\n\n### `auth`\n\n```bash\nswitchbot auth login [--no-open] [--timeout 60]\nswitchbot auth keychain describe/set/get/migrate/delete\n```\n\n### `config`\n\n```bash\nswitchbot config set-token \u003ctoken\u003e \u003csecret\u003e\nswitchbot config show\nswitchbot config list-profiles\n```\n\n### `mcp`\n\n```bash\nswitchbot mcp serve    # stdio MCP server — 24 tools\n```\n\n### `webhook`\n\n```bash\nswitchbot webhook setup \u003curl\u003e\nswitchbot webhook query [--details \u003curl\u003e]\nswitchbot webhook update \u003curl\u003e --enable/--disable\nswitchbot webhook delete \u003curl\u003e\n```\n\n### `events`\n\n```bash\nswitchbot events tail [--filter deviceId=X] [--port 8080]\nswitchbot events mqtt-tail [--max 10] [--for 30s] [--json]\n```\n\n### `status-sync`\n\n```bash\nswitchbot status-sync start --openclaw-model home-agent\nswitchbot status-sync status --json\nswitchbot status-sync stop\n```\n\n### `rules` / `daemon`\n\nPolicy-driven automations. Triggers: `mqtt` · `cron` · `webhook`. Conditions: `time_between` · `device_state` · `event_count` · `llm`. Actions: `command` · `notify`.\n\n```bash\nswitchbot rules lint\nswitchbot rules list/explain/run/simulate\nswitchbot rules tail/replay/summary/conflicts/doctor\nswitchbot rules suggest --intent \"turn off AC at 11pm\" [--llm auto]\nswitchbot daemon start/stop/reload/status\n```\n\n### `plan`\n\nDeclarative batch operations. A plan file has `version`, `description`, and a `steps` array.\n\n```bash\nswitchbot plan schema/suggest/validate\nswitchbot plan run plan.json [--dry-run] [--require-approval]\nswitchbot plan save/review/approve/execute\n```\n\n### `policy`\n\n```bash\nswitchbot policy new/validate/migrate/backup/restore\n```\n\n### `doctor` / `health`\n\n```bash\nswitchbot doctor [--json] [--fix --yes]\nswitchbot health check [--json] [--prometheus]\nswitchbot health serve [--port 3100]\n```\n\n### Other\n\n```bash\nswitchbot history show [--limit 20]\nswitchbot quota status/reset\nswitchbot upgrade-check [--json]\nswitchbot catalog show/search\nswitchbot schema export [--type 'Strip Light']\nswitchbot capabilities --json\nswitchbot cache show/clear\nswitchbot reset [--yes] [--keep-credentials]\nswitchbot completion bash/zsh/fish/powershell\n```\n\n---\n\n## Global options\n\n| Flag | Description |\n|---|---|\n| `--json` | Raw JSON output |\n| `--format \u003cfmt\u003e` | `tsv` / `yaml` / `jsonl` / `id` |\n| `--fields \u003ccols\u003e` | Comma-separated column filter |\n| `--dry-run` | Preview mutating requests without sending |\n| `--verbose` | Log HTTP request/response to stderr |\n| `--timeout \u003cms\u003e` | HTTP timeout (default `30000`) |\n| `--config \u003cpath\u003e` | Override credential file location |\n| `--profile \u003cname\u003e` | Named credential profile |\n| `--cache \u003cdur\u003e` | Cache TTL (`5m`, `1h`, `off`, `auto`) |\n| `--no-cache` | Disable all cache reads |\n| `--retry-on-429 \u003cn\u003e` | Max 429 retry attempts (default `3`) |\n| `--audit-log` | Append mutating commands to audit log |\n\n---\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| `0` | Success |\n| `1` | Runtime error (API / network / credentials) |\n| `2` | Usage error (bad flag / unknown command / validation) |\n\n---\n\n## Environment variables\n\n| Variable | Description |\n|---|---|\n| `SWITCHBOT_TOKEN` | API token (overrides config file) |\n| `SWITCHBOT_SECRET` | API secret (overrides config file) |\n| `NO_COLOR` | Disable ANSI colors |\n| `CODEX_GIT_MARKETPLACE_REF` | Git ref used when registering the Codex plugin via the git marketplace (default: `main`) |\n\n---\n\n## Development\n\n```bash\nnpm install \u0026\u0026 npm run build\nnpm run dev -- \u003cargs\u003e   # run from TypeScript via tsx\nnpm test                # Vitest suite\n```\n\n## License\n\n[MIT](./LICENSE) © chenliuyun\n\n---\n\n- [SwitchBot API v1.1](https://github.com/OpenWonderLabs/SwitchBotAPI) · Base URL: `https://api.switch-bot.com` · Rate limit: 10,000 req/day\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenwonderlabs%2Fswitchbot-openapi-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenwonderlabs%2Fswitchbot-openapi-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenwonderlabs%2Fswitchbot-openapi-cli/lists"}