Skip to content
Back to search

switchbot

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openwonderlabs--switchbot-openapi-cli/badge.svg)](/listings/openwonderlabs--switchbot-openapi-cli)

HTML

<a href="/listings/openwonderlabs--switchbot-openapi-cli"><img src="/api/listings/openwonderlabs--switchbot-openapi-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

1. Open **Profile → Preferences → About** (app V9.0 or newer). 2. Tap **App Version** 10 times to expose **Developer Options**. 3. Open **Developer Options → Get Token** and copy the token and secret. 4. For older apps, App Version is directly under Preferences. See the [official credential instructions](https://github.com/OpenWonderLabs/SwitchBotAPI/blob/dc9a6b0e4ad77882c72d186ecd5d134113acdad0/README.md#getting-started).

Then run:

switchbot config set-token <token> <secret>

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "switchbot",
  4. "owner": {
  5. "name": "OpenWonderLabs",
  6. "email": "developer@wondertechlabs.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "switchbot",
  11. "version": "0.2.0",
  12. "author": {
  13. "name": "OpenWonderLabs"
  14. },
  15. "homepage": "https://github.com/OpenWonderLabs/switchbot-openapi-cli",
  16. "source": "./packages/claude-code-plugin/plugins/switchbot",
  17. "description": "Control SwitchBot smart-home devices from Claude Code via MCP.",
  18. "category": "Productivity"
  19. }
  20. ]
  21. }
README.md · README · 520 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # @switchbot/openapi-cli
  2. [![npm version](https://img.shields.io/npm/v/@switchbot/openapi-cli.svg)](https://www.npmjs.com/package/@switchbot/openapi-cli)
  3. [![npm downloads](https://img.shields.io/npm/dm/@switchbot/openapi-cli.svg)](https://www.npmjs.com/package/@switchbot/openapi-cli)
  4. [![license](https://img.shields.io/npm/l/@switchbot/openapi-cli.svg)](./LICENSE)
  5. [![node](https://img.shields.io/node/v/@switchbot/openapi-cli.svg)](https://nodejs.org)
  6. [![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)
  7. SwitchBot smart home CLI — control devices, run scenes, stream events, and plug AI agents into your home via the built-in MCP server.
  8. - **npm:** [`@switchbot/openapi-cli`](https://www.npmjs.com/package/@switchbot/openapi-cli)
  9. - **Source / issues:** [github.com/OpenWonderLabs/switchbot-openapi-cli](https://github.com/OpenWonderLabs/switchbot-openapi-cli)
  10. - **Releases / changelog:** [GitHub Releases](https://github.com/OpenWonderLabs/switchbot-openapi-cli/releases)
  11. ---
  12. **Human** — start with [Quick start](#quick-start): colored tables, error hints, shell completion, `switchbot doctor`.
  13. **Script** — start with [Global options](#global-options): `--json`, `--format tsv/yaml/id`, `--fields`, stable exit codes, audit log.
  14. **Agent** — start with [`docs/agent-guide.md`](./docs/agent-guide.md): `mcp serve`, `schema export`, `plan run`, destructive-command guards.
  15. Every surface shares the same catalog, cache, and HMAC client.
  16. ---
  17. ## Installation
  18. ```bash
  19. npm install -g @switchbot/openapi-cli
  20. ```
  21. Requires Node.js ≥ 18. Run `switchbot auth login` to authenticate via browser — no Developer Options needed.
  22. To use API token/secret directly instead, first obtain your credentials from the SwitchBot app:
  23. 1. Open **Profile → Preferences → About** (app V9.0 or newer).
  24. 2. Tap **App Version** 10 times to expose **Developer Options**.
  25. 3. Open **Developer Options → Get Token** and copy the token and secret.
  26. 4. For older apps, App Version is directly under Preferences. See the [official credential instructions](https://github.com/OpenWonderLabs/SwitchBotAPI/blob/dc9a6b0e4ad77882c72d186ecd5d134113acdad0/README.md#getting-started).
  27. Then run:
  28. ```bash
  29. switchbot config set-token <token> <secret>
  30. ```
  31. ---
  32. ## Supported devices
  33. Run `switchbot catalog show` for the effective catalog, including aliases and per-command details. Discovery follows the pinned official documentation; undocumented defaults and live-device behavior are not certified by local metadata.
  34. | Category | Devices |
  35. | --- | --- |
  36. | **Lighting** | Color Bulb · Strip Light · Strip Light 3 · RGBICWW Strip Light · RGBICWW Light Bars · 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 |
  37. | **Climate** | Humidifier · Humidifier2 · Air Purifier VOC · Air Purifier Table VOC · Air Purifier PM2.5 · Air Purifier Table PM2.5 · Smart Radiator Thermostat |
  38. | **Security** | Smart Lock · Smart Lock Pro · Smart Lock Pro Wifi · Smart Lock Ultra · Smart Lock Ultra Max · Lock Lite · Lock Vision · Lock Vision Pro · Keypad · Keypad Touch · Keypad Vision · Keypad Vision Pro · Garage Door Opener · Video Doorbell |
  39. | **Curtains & blinds** | Curtain · Curtain3 · Curtain 4 · Blind Tilt · Roller Shade |
  40. | **Power** | Plug · Plug Mini (US) · Plug Mini (JP) · Plug Mini (EU) · Relay Switch 1 · Relay Switch 1PM · Relay Switch 2PM |
  41. | **Fans** | Battery Circulator Fan · Battery Circulator Fan 2 Pro · Circulator Fan · Standing Circulator Fan |
  42. | **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 K11 Plus Pro · Robot Vacuum Cleaner K20 Plus Pro |
  43. | **Sensors** _(read-only)_ | Meter · MeterPlus · WoIOSensor · MeterPro · MeterPro(CO2) · WeatherStation · Motion Sensor · Presence Sensor · Contact Sensor · Water Detector · Wallet Finder Card |
  44. | **Hubs** _(read-only)_ | Hub · Hub Plus · Hub Mini · Hub 2 · Hub 3 · AI Hub |
  45. | **Cameras** | Indoor Cam · Pan/Tilt Cam · Pan/Tilt Cam 2K · Pan/Tilt Cam Plus 2K · Pan/Tilt Cam Plus 3K · Outdoor Spotlight Cam · Outdoor Pan/Tilt Cam 3K _(status only)_ · Solar Pan/Tilt Cam 2K |
  46. | **Other** | Bot · AI Art Frame · AI Art Frame Luma · AI MindClip · Kata Friends · Home Climate Panel · Remote |
  47. | **IR virtual remotes** _(via Hub)_ | Air Conditioner · TV · Streamer · Set Top Box · DVD · Speaker · Fan · Light · Others |
  48. ### Device contract notes
  49. The capabilities below are available starting in CLI 3.10.0.
  50. - Light Bars accept object parameters. For example: `switchbot devices command <lightBarId> setLightEffect '{"effectId":1}'`; `effectId` is an integer from 0 through 25.
  51. - Outdoor Pan/Tilt Cam 3K is status-only. Camera status may include `latestImage` as `{ imageUrl, expireAt }`; `expireAt` is Unix seconds. Treat cached URLs as potentially expired, do not download or persist image bytes, and query again with `--no-cache` when a fresh status is needed.
  52. - Solar Pan/Tilt Cam 2K supports motion-detection enable/disable only. Disabling detection is destructive and follows the reviewed approval path; it is not a substitute for camera streaming or PTZ control.
  53. - Light Bars webhook field shapes are documented, but their exact `context.deviceType` identifier is not discoverable from the official material. The CLI does not guess a mapping.
  54. ---
  55. ## Quick start
  56. ```bash
  57. switchbot auth login # browser OAuth — saves to OS keychain
  58. switchbot config set-token <token> <secret> # or set credentials manually
  59. switchbot devices list # list all devices
  60. switchbot devices command <id> turnOn
  61. switchbot doctor # self-check
  62. ```
  63. ---
  64. ## Codex integration
  65. The existing [`@switchbot/codex-plugin`](https://www.npmjs.com/package/@switchbot/codex-plugin)
  66. provides Skill + MCP integration. Plugin 0.2.0 requires CLI ≥3.9.0.
  67. The setup commands below install this MCP-backed plugin.
  68. **Recommended — paste into Codex chat:**
  69. ```text
  70. Please set up the SwitchBot integration for me by running:
  71. npx @switchbot/openapi-cli codex setup
  72. Then restart Codex and confirm it's working.
  73. ```
  74. `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.
  75. **Or install directly:**
  76. ```bash
  77. npm install -g @switchbot/openapi-cli @switchbot/codex-plugin
  78. switchbot codex setup # one-shot bootstrap: register, auth, verify
  79. ```
  80. **Or install via Codex Plugin Marketplace** (requires Codex CLI with marketplace support):
  81. ```bash
  82. codex plugin marketplace add OpenWonderLabs/switchbot-openapi-cli
  83. codex plugin add switchbot@switchbot
  84. switchbot auth login
  85. ```
  86. ---
  87. ## Claude Code integration
  88. **Already configured? Paste into Claude Code chat:**
  89. ```text
  90. Is my SwitchBot integration working? Please check and list my devices.
  91. ```
  92. Claude will call `account_overview` or `switchbot doctor` to verify — no terminal needed.
  93. **Fresh setup — paste into Claude Code chat:**
  94. ```text
  95. Please set up my SwitchBot integration by running:
  96. npx @switchbot/openapi-cli claude-code setup
  97. ```
  98. 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.
  99. **Or run manually in your terminal:**
  100. ```bash
  101. npm install -g @switchbot/openapi-cli
  102. switchbot claude-code setup
  103. ```
  104. The optional skill package [`@switchbot/claude-code-plugin`](https://www.npmjs.com/package/@switchbot/claude-code-plugin) bundles the SKILL.md context document. Install it only if your environment does not already load the skill automatically.
  105. **Or install via Claude Code Plugin Marketplace** (requires Claude Code with plugin marketplace support enabled):
  106. ```text
  107. /plugin marketplace add OpenWonderLabs/switchbot-openapi-cli
  108. /plugin install switchbot@switchbot
  109. ```
  110. **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`.
  111. ---
  112. ## Gemini CLI integration
  113. The Gemini extension is in [`packages/gemini-extension/`](./packages/gemini-extension/) — it provides 29 MCP tools (15 readonly, 18 default, 29 with `--tools all`; including 3 deprecated aliases), a GEMINI.md context file, and 23 slash commands. Plugin/extension 0.2.0 requires CLI ≥3.9.0.
  114. **Recommended — paste into Gemini CLI chat:**
  115. ```text
  116. Please set up the SwitchBot integration for me by running:
  117. npx @switchbot/openapi-cli gemini setup
  118. Then restart Gemini CLI and confirm it's working by listing my devices.
  119. ```
  120. `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.
  121. **Or install the full extension (adds 23 slash commands + GEMINI.md context):**
  122. ```bash
  123. npm install -g @switchbot/openapi-cli
  124. git clone https://github.com/OpenWonderLabs/switchbot-openapi-cli.git
  125. gemini extensions link ./switchbot-openapi-cli/packages/gemini-extension
  126. ```
  127. Authenticate with `switchbot auth login`, or set both `SWITCHBOT_TOKEN` and `SWITCHBOT_SECRET` in the host environment. Empty extension environment placeholders do not authenticate you; the CLI can still use its OS-keychain/file fallback.
  128. **Or run MCP-only setup directly in your terminal:**
  129. ```bash
  130. npm install -g @switchbot/openapi-cli
  131. switchbot gemini setup
  132. ```
  133. **Verify:**
  134. ```bash
  135. switchbot gemini doctor
  136. ```
  137. After setup, restart Gemini CLI and ask: "List my SwitchBot devices."
  138. ---
  139. ## OpenClaw integration
  140. The OpenClaw integration is distributed as [`@switchbot/openclaw-skill`](https://www.npmjs.com/package/@switchbot/openclaw-skill), an MCP bootstrap bundle rather than a native extension or conversational Skill.
  141. **Paste into OpenClaw chat:**
  142. ```text
  143. Install the SwitchBot CLI, pack @switchbot/openclaw-skill, and install the
  144. resulting local .tgz bundle with OpenClaw. Authenticate with switchbot auth login.
  145. Do not use switchbot install --agent openclaw; that target is not supported.
  146. ```
  147. **Or install directly:**
  148. ```bash
  149. npm install -g @switchbot/openapi-cli@^3.9.0
  150. npm pack @switchbot/openclaw-skill@0.2.0
  151. openclaw plugins install ./switchbot-openclaw-skill-0.2.0.tgz --force --accept-capabilities
  152. switchbot auth login
  153. ```
  154. `switchbot-openclaw setup` verifies CLI ≥3.9.0 and credential readiness. Its stdio bootstrap writes only JSON-RPC on stdout; setup diagnostics go to stderr. OpenClaw bundle loading, MCP startup and native daemon helpers are separate capabilities—see the package README for the supported route.
  155. Use an explicit Claude-bundle marker and a local directory or archive route.
  156. `openclaw plugins install @switchbot/openclaw-skill` takes the native npm-package
  157. path and is not the bundle route. See [host verification boundaries](./docs/host-compatibility.md).
  158. ---
  159. ## Credentials
  160. > **Recommended:** use `switchbot auth login` for browser-based OAuth. Credentials are stored in the OS keychain when available, otherwise in the local config file.
  161. Priority: complete env vars → OS keychain → `~/.switchbot/config.json`.
  162. `--config <path>` bypasses the keychain but not complete environment credentials.
  163. `config set-token` writes the file; an existing keychain entry still takes
  164. precedence unless `--config` is used.
  165. ```bash
  166. switchbot auth login # browser OAuth — opens login page, saves to OS keychain
  167. switchbot config set-token <token> <secret> # manual setup (alternative)
  168. export SWITCHBOT_TOKEN=... SWITCHBOT_SECRET=... # CI / env override
  169. switchbot auth keychain set/get/delete # OS keychain management
  170. ```
  171. ### Switching accounts and caches
  172. Successful `auth login`, `auth keychain set/delete/migrate`, and
  173. `config set-token` invalidate the affected credential scope's device list,
  174. status, primed credentials, and idempotency results. Other running CLI/MCP
  175. processes observe the change at their next cache or request boundary. A request
  176. already in flight is not automatically retried under the new account; if it
  177. was already sent, check its outcome before retrying.
  178. Implicit default and `--profile default` share `~/.switchbot/devices.json`
  179. and `status.json`. Named profiles use separate full-SHA-256 cache directories.
  180. Older short-hash inventory/status caches are ignored; refresh them with
  181. `switchbot --profile <name> devices list`. Profile credentials are unchanged.
  182. `--config` stores caches beside the selected file; config files in the same
  183. directory share that cache scope, so use separate directories for separate
  184. accounts. Internal cache files contain a non-secret credential revision; CLI,
  185. MCP, and audit output formats are unchanged.
  186. Direct edits to credential files, environment variables, or an external
  187. keychain tool do not publish this invalidation. Stop affected long-running
  188. processes, run `switchbot [--profile <name> | --config <path>] cache clear`,
  189. then restart them with the intended credentials. Restart an MQTT subscription
  190. or rules daemon after changing accounts; its existing event stream is not
  191. rebound automatically. Audit, policy, and event-history files are not cleared.
  192. [Details and safety boundaries](./docs/agent-guide.md#profiles-and-credential-refresh).
  193. If a newly selected native keychain is locked or unavailable, cloud requests
  194. fail closed rather than using older file credentials. Offline CLI commands,
  195. MCP catalog/history/policy tools, and credential repair remain available.
  196. MCP policy validation requires credentials only with `live: true`.
  197. HTTP MCP also honors `--config` when a request selects a named profile; the
  198. override selects the account, while profile-name and bearer-token checks
  199. remain enforced.
  200. For HTTP `401`, check the active token/secret, signature and system clock;
  201. use `auth login` or replace the credential source locally, never paste secrets
  202. into chat. For `429`, honor `Retry-After` and reduce request frequency.
  203. Throttling is not necessarily daily-quota exhaustion; local quota counters
  204. are not the server's authoritative remaining allowance.
  205. ---
  206. ## Commands
  207. ### `devices`
  208. ```bash
  209. switchbot devices list [--wide] [--filter 'type=Bot'] [--json]
  210. switchbot devices status <id> [--ids A,B,C]
  211. switchbot devices diary <id> --start <unix-ms> --end <unix-ms> # Kata diary window ≤31 days
  212. switchbot devices command <id> <cmd> [parameter]
  213. switchbot devices expand <id> setAll --temp 26 --mode cool # named flags for packed params
  214. switchbot devices watch <id> [--interval 10s] [--for 5m]
  215. switchbot devices batch turnOff --filter 'type=Bot'
  216. switchbot devices meta set <id> --alias "Office Light"
  217. ```
  218. ### `scenes`
  219. ```bash
  220. switchbot scenes list
  221. switchbot scenes execute <sceneId>
  222. ```
  223. ### `mindclip`
  224. ```bash
  225. switchbot mindclip recordings --device <id> --page <n> --size <n>
  226. switchbot mindclip recording <id> [--language en|zh]
  227. switchbot mindclip summary <id>
  228. switchbot mindclip transcript <id>
  229. switchbot mindclip todos --completed 0|1|2 --page <n> --size <n> [--category 0..5]
  230. switchbot mindclip daily --date YYYY-MM-DD
  231. switchbot mindclip weekly --week YYYY-Www
  232. switchbot mindclip urgent-todos --date YYYY-MM-DD
  233. ```
  234. The CLI and MCP require the official device/pagination/date/week query fields.
  235. They do not infer server defaults. Legacy extra filters and numeric filter meanings
  236. remain [unverified](docs/openapi-alignment-ambiguities.md).
  237. ### `codex`
  238. ```bash
  239. switchbot codex setup [--yes] [--dry-run] [--json] # full bootstrap
  240. switchbot codex doctor [--quiet] [--json] # 7-check health summary
  241. switchbot codex repair [--skip re-auth] [--yes] # re-register + re-verify
  242. ```
  243. ### `gemini`
  244. ```bash
  245. switchbot gemini setup [--yes] [--dry-run] [--json] # register MCP in ~/.gemini/settings.json
  246. switchbot gemini doctor [--quiet] [--json] # check CLI + MCP + credentials health
  247. ```
  248. ### `auth`
  249. ```bash
  250. switchbot auth login [--no-open] [--timeout 60]
  251. switchbot auth keychain describe/set/get/migrate/delete
  252. ```
  253. ### `config`
  254. ```bash
  255. switchbot config set-token <token> <secret>
  256. switchbot config show
  257. switchbot config list-profiles
  258. ```
  259. ### `mcp`
  260. ```bash
  261. switchbot mcp serve # stdio — default 18 tools; readonly 15; --tools all 29
  262. ```
  263. Read endpoints added in CLI 3.9.0: `mindclip transcript <id>` and `devices diary <id> --start <unix-ms> --end <unix-ms>`. Both have readonly MCP equivalents; diary windows are limited to 31 days and embedded detail strings remain raw.
  264. ### `webhook`
  265. ```bash
  266. switchbot webhook setup <url>
  267. switchbot webhook query [--details <url>]
  268. switchbot webhook update <url> --enable/--disable
  269. switchbot webhook delete <url>
  270. ```
  271. ### `events`
  272. ```bash
  273. switchbot events tail [--filter deviceId=X] [--port 8080]
  274. switchbot events mqtt-tail [--max 10] [--for 30s] [--json]
  275. ```
  276. ### `status-sync`
  277. ```bash
  278. switchbot status-sync start --openclaw-model home-agent
  279. switchbot status-sync status --json
  280. switchbot status-sync stop
  281. ```
  282. ### `rules` / `daemon`
  283. Policy-driven automations. Triggers: `mqtt` · `cron` · `webhook`. Conditions: `time_between` · `device_state` · `event_count` · `llm`. Actions: `command` · `notify`.
  284. ```bash
  285. switchbot rules lint
  286. switchbot rules list/explain/run/simulate
  287. switchbot rules tail/replay/summary/conflicts/doctor
  288. switchbot rules suggest --intent "turn off AC at 11pm" [--llm auto]
  289. switchbot daemon start/stop/reload/status
  290. ```
  291. Existing rules may use either `setColor 255 0 0` or `setColor 255:0:0`;
  292. both send `255:0:0`. The same applies to `setColorLightRGB`. JSON object
  293. parameters and audit records retain their existing formats.
  294. ### `plan`
  295. Declarative batch operations. A plan file has `version`, `description`, and a `steps` array.
  296. ```bash
  297. switchbot plan schema/suggest/validate
  298. switchbot plan run plan.json [--dry-run] [--require-approval]
  299. switchbot plan save/review/approve/execute
  300. ```
  301. ### `policy`
  302. ```bash
  303. switchbot policy new/validate/migrate/backup/restore
  304. ```
  305. ### `doctor` / `health`
  306. ```bash
  307. switchbot doctor [--json] [--fix --yes]
  308. switchbot health check [--json] [--prometheus]
  309. switchbot health serve [--port 3100]
  310. ```
  311. The 22 doctor checks are `node`, `path`, `credentials`, `keychain`, `profiles`,
  312. `catalog`, `catalog-coverage`, `catalog-schema`, `inventory`, `cache`, `quota`,
  313. `clock`, `mqtt`, `mcp`, `release-notes`, `policy`, `audit`, `daemon`, `health`,
  314. `notify-connectivity`, `local-llm-reachable` and `daemon-ipc`.
  315. Use `doctor --list --json` to discover them without running probes.
  316. ### Other
  317. ```bash
  318. switchbot history show [--limit 20]
  319. switchbot quota status/reset
  320. switchbot upgrade-check [--json]
  321. switchbot catalog show/search
  322. switchbot schema export [--type 'Strip Light']
  323. switchbot capabilities --json
  324. switchbot cache show/clear
  325. switchbot reset [--yes] [--keep-credentials]
  326. switchbot completion bash/zsh/fish/powershell
  327. ```
  328. ---
  329. ## Global options
  330. | Flag | Description |
  331. | --- | --- |
  332. | `--json` | Raw JSON output |
  333. | `--format <fmt>` | `tsv` / `yaml` / `jsonl` / `id` |
  334. | `--fields <cols>` | Comma-separated column filter |
  335. | `--dry-run` | Preview mutating requests without sending |
  336. | `--verbose` | Log HTTP request/response to stderr |
  337. | `--timeout <ms>` | HTTP timeout (default `30000`) |
  338. | `--config <path>` | Override credential file location |
  339. | `--profile <name>` | Named credential profile |
  340. | `--cache <dur>` | Cache TTL (`5m`, `1h`, `off`, `auto`) |
  341. | `--no-cache` | Disable all cache reads |
  342. | `--retry-on-429 <n>` | Max 429 retry attempts (default `3`) |
  343. | `--audit-log` | Append mutating commands to audit log |
  344. | `--audit-log-path <path>` | Custom audit path; use together with `--audit-log` |
  345. ---
  346. ## Exit codes
  347. | Code | Meaning |
  348. | --- | --- |
  349. | `0` | Success |
  350. | `1` | Runtime error (API / network / credentials) |
  351. | `2` | Usage error (bad flag / unknown command / validation) |
  352. Policy commands retain their documented specialized exit codes (including YAML parse, existing-file and unsupported-version errors). See `switchbot policy --help`. JSON output uses `{schemaVersion: "1.2", data|error}`; `completion` emits shell source and rejects JSON mode.
  353. ---
  354. ## Environment variables
  355. | Variable | Description |
  356. | --- | --- |
  357. | `SWITCHBOT_TOKEN` | API token (overrides config file) |
  358. | `SWITCHBOT_SECRET` | API secret (overrides config file) |
  359. | `SWITCHBOT_POLICY_PATH` | Override the shared policy path (default `~/.config/openclaw/switchbot/policy.yaml`) |
  360. | `NO_COLOR` | Disable ANSI colors |
  361. | `CODEX_GIT_MARKETPLACE_REF` | Git ref used when registering the Codex plugin via the git marketplace (default: `main`) |
  362. ---
  363. ## Development
  364. Verified CLI regression suite: 3211 tests. Plugin workspace checks are separate.
  365. ```bash
  366. npm install && npm run build
  367. npm run dev -- <args> # run from TypeScript via tsx
  368. npm test # Vitest suite
  369. npm run test:account-lifecycle # focused account/cache/MCP regressions
  370. npm run test:coverage # suite plus coverage thresholds
  371. ```
  372. CI runs CLI regressions on Node 18/20/22/24, enforces coverage on Node 24,
  373. and checks all Markdown and workflow schemas. Native credential checks and
  374. candidate publication/promotion gates are described in the
  375. [release pipeline](docs/release-pipeline.md).
  376. ## License
  377. [MIT](./LICENSE) © chenliuyun
  378. ---
  379. - [SwitchBot API v1.1](https://github.com/OpenWonderLabs/SwitchBotAPI) · Base URL: `https://api.switch-bot.com` · Rate limit: 10,000 req/day

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.