SmartThings Direct

Direct SmartThings hub control via the official SmartThings CLI. List devices, read device status, and execute capability commands without going through Home...

Security Scan

This skill is internally consistent: it uses the SmartThings CLI to control devices, requires the smartthings binary, and the only sensitive requirement is authenticated access to your SmartThings account (browser login or a PAT).

Purpose & Capability

Name/description match the actual behavior: the skill invokes the official SmartThings CLI to list devices, read status, and send capability commands. The required binary (smartthings) is exactly what is needed and nothing unrelated is requested.

Instruction Scope

The SKILL.md and the included script only instruct the agent to run smartthings CLI commands and jq, plus suggest where the CLI stores its config. There is no attempt to read unrelated system files or exfiltrate data to external endpoints. The docs do instruct how to place a PAT in the CLI config file (a sensitive action), which is expected for this kind of integration.

Install Mechanism

No install spec is included (instruction-only), and the doc recommends installing via Homebrew or npm — both are standard, low-risk sources for this CLI. No arbitrary download URLs or archive extraction are present.

Credentials

The skill declares no required env vars and does not request unrelated credentials. However, to operate it needs authenticated SmartThings access (browser OAuth or a Personal Access Token). PAT scopes listed (read/write/execute for devices and scenes) are broad but necessary for device control; treat PATs as highly sensitive. The SKILL.md notes config file paths where a token could be stored, which is expected but important to be aware of.

Persistence & Privilege

always is false and the skill does not request persistent system-wide privileges. The CLI itself will store tokens in its own config if you choose PAT or browser refresh tokens, which is normal for the CLI but outside the skill's direct behavior.

Assessment

This skill looks coherent and uses the official SmartThings CLI. Before installing, ensure: (1) you have the smartthings CLI installed and trust the runtime that will execute it; (2) the agent will need authenticated access — prefer browser OAuth (the CLI opens a browser and stores a refresh token) over pasting a PAT; (3) if you must use a PAT, be aware it grants broad read/write/execute control over your devices and scenes and may be short-lived (the doc notes 24-hour expiry for newer PATs); (4) check where the CLI stores its config (~/.config/@smartthings/cli or ~/Library/Preferences/...), because storing a token there gives whoever can run the CLI full control; (5) the provided st-find.sh script is simple and only queries devices via the CLI and jq. If you are uncomfortable giving the agent account-level control, do not provide a PAT or global credentials — instead use interactive browser login or limit how the agent can invoke the skill.

Direct control of a SmartThings hub using the official @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

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

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:

   smartthings devices --token <uuid>
   

   or add to the config file:
   • macOS: ~/Library/Preferences/@smartthings/cli/config.yaml
   • Linux: ~/.config/@smartthings/cli/config.yaml

   default:
     token: your-pat-uuid-here
   

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

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.

# 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

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:

   scripts/st-find.sh "living room"
   

   or directly:

   smartthings devices --json | jq '.[] | select(.label | test("living room"; "i")) | {deviceId, label}'
   

2. Check current status before acting (optional but safer):

   smartthings devices:status <id>
   

3. Send the command:

   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.