SmartThings Direct

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.

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

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:
     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

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.