Skill: keenranger/smartthings-direct (version 0.1.0)

--- name: smartthings-direct description: Direct SmartThings hub control via the official SmartThings CLI. List devices, read device status, and execute capability commands without going through Home Assistant. Use when the user asks to control a SmartThings device, check device state, run a scene, or when "smartthings" / "ST" is mentioned. homepage: https://github.com/SmartThingsCommunity/smartthings-cli metadata: clawdbot: emoji: "🏠" requires: bins: ["smartthings"] --- # SmartThings Direct Direct control of a SmartThings hub using the official [`@smartthings/cli`](https://github.com/SmartThingsCommunity/smartthings-cli). This is the low-level path — bypasses Home Assistant and Matter bridging. Use this when you want to hit SmartThings devices directly. For the Home Assistant / Matter setup, see the sibling `smart-home` skill instead. ## Install ```bash # macOS (recommended) brew install smartthingscommunity/smartthings/smartthings # or npm (Node 24.8+) npm install --global @smartthings/cli ``` Binary: `smartthings` (alias `st`). Verify: `smartthings --version`. ## Auth Two options. **Browser login is preferred** for long-lived use because the CLI stores a refresh token. ### Browser (preferred) Run any command — the CLI opens a browser for Samsung account OAuth on first use. ```bash smartthings locations # first call triggers login ``` ### Personal Access Token (PAT) 1. Create a PAT at https://account.smartthings.com/tokens 2. Required scopes: `r:devices:*`, `w:devices:*`, `x:devices:*`, `r:locations:*`, `r:scenes:*`, `x:scenes:*` 3. Either pass per command: ```bash smartthings devices --token <uuid> ``` or add to the config file: - macOS: `~/Library/Preferences/@smartthings/cli/config.yaml` - Linux: `~/.config/@smartthings/cli/config.yaml` ```yaml default: [REDACTED_SECRET] ``` **Heads up:** PATs created after 2024-12-30 expire in **24 hours**. For durable agent use, prefer browser auth or expect to reissue the token. Confirm config path any time with `smartthings config`. ## Core commands ### Devices ```bash smartthings devices # list all devices smartthings devices --json # JSON output smartthings devices <id> # device detail + capabilities smartthings devices:status <id> # current attribute values smartthings devices:health <id> # online/offline smartthings devices:capability-status <id> <component> <capability> ``` ### Execute commands Format: `[component:]<capability>:<command>[(args)]` — `component` defaults to `main`. ```bash # Switch on/off smartthings devices:commands <id> switch:switch:on smartthings devices:commands <id> switch:switch:off # Dimmer to 50 % smartthings devices:commands <id> main:switchLevel:setLevel\(50\) # Thermostat cool setpoint to 24 °C smartthings devices:commands <id> main:thermostatCoolingSetpoint:setCoolingSetpoint\(24\) # Color temperature smartthings devices:commands <id> main:colorTemperature:setColorTemperature\(3000\) ``` Parentheses need escaping in bash/zsh. Running `devices:commands` with no args starts an interactive guided prompt — handy for discovering the right capability call. ### Locations, rooms, scenes, capabilities ```bash smartthings locations smartthings rooms --location-id <loc-id> smartthings scenes smartthings scenes:execute <scene-id> smartthings capabilities # catalog of standard capabilities ``` ### Output flags | Flag | Effect | |------|--------| | `-j`, `--json` | JSON to stdout | | `-y`, `--yaml` | YAML | | `-o <file>` | write to file (extension sets format) | No built-in field picker — pipe JSON through `jq`. ## Typical agent workflow When the user says something like "turn off the living room light": 1. Resolve name → device id: ```bash scripts/st-find.sh "living room" ``` or directly: ```bash smartthings devices --json | jq '.[] | select(.label | test("living room"; "i")) | {deviceId, label}' ``` 2. Check current status before acting (optional but safer): ```bash smartthings devices:status <id> ``` 3. Send the command: ```bash smartthings devices:commands <id> switch:switch:off ``` 4. Confirm result by re-reading status if the action is consequential (HVAC setpoint, scene execute). ## Rate limits - Device commands: **12/min per device**, max 10 commands per request - Locations: 100/min read, 20/hr write - Rooms: 50/hr all ops - Scenes: 50/min execute, 50/min list - `HTTP 429` = rate limited, `HTTP 422` = guardrail violation Back off rather than retrying tight. ## Notes - Flags come **after** the subcommand: `smartthings devices -j`, not `smartthings -j devices`. - `SMARTTHINGS_PROFILE` env var switches config profiles; there is no `SMARTTHINGS_TOKEN` env var. - This skill is intentionally thin. Prefer invoking the CLI directly over adding wrapper scripts.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)