SmartThings Direct#

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#

FlagEffect-j, --jsonJSON to stdout-y, --yamlYAML-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.