Overview

SmartThings CLI

The SmartThings CLI is a tool to help with developing SmartApps and drivers for the SmartThings ecosystem.

• Usage
• Helpful Hints
• Commands
• Configuration and Logging

Usage

Installation

Homebrew (MacOS)

Note that the MacOS binaries require at least MacOS 13.5.

brew install smartthingscommunity/smartthings/smartthings

Windows

Download and run the smartthings.msi installer from the latest Release.

Standalone Installation (Linux and others)

1. Download the appropriate zipped binary from the latest Release.
2. Extract and install it on your system path. It does not need administrator privileges but will need to be executable.

Other

The CLI can be used on any platform that supports Node 24.

First, install at least Node version 24.8.0 on your machine. The official Node release can be found here:

https://nodejs.org/en/download/current

Then, install the CLI.

npm install --global @smartthings/cli

Verify Installation

Run smartthings --version and verify the version matches the latest release.

Getting Started

1. Run smartthings --help to get more information on each command.
2. Run a specific command with smartthings <command>.

Input and Output Considerations

Many commands in the CLI handle complex input and/or output, mostly for use with the SmartThings REST API.

Complex input can always be passed as JSON or YAML and in a couple cases a "question and answer" mode is provided.

The output format will match the input format unless otherwise specified. When there is no input specified the default will be a user-friendly (often table) formatted style if the output is going to the console or JSON otherwise.

| Name | Shortcut | Description | | -- | -- | -- | | json | j | Write output in JSON format. | | yaml | y | Write output in YAML format. | | indent | | Specify the number of spaces for YAML or JSON output | | input | i | Specify a filename for input. | | output | o | Specify a filename for output. The extension of this file will control its type unless overridden with --json or --yaml. |

Shell Completions

On MacOS with zsh, run smartthings generate-completions-script >> ~/.zshrc. Note that when running this command, a comment suggests adding to .zprofile on MacOS but I found this did not work for me.

Linux instructions can be found here. These have not been tested yet.

https://yargs.js.org/docs/#api-reference-completioncmd-description-fn

Authentication

The CLI supports an automatic login flow that pops up a browser window asking you to log in and give the CLI permission to access your account. The CLI will automatically request login as needed.

You can also use a personal access token (PAT) for authentication by passing a --token <uuid> flag to commands or by creating a configuration file and including the token in a token key for your profile. We generally don't recommend this approach since it less secure, given that PATs don't expire unless revoked by the user, but it can be useful when working with headless servers or for users who frequently switch between accounts.

Helpful Hints

1. You can get more specific information about any command or sub-hierarchy of commands by using --help with a specific command or branch. For example, you can run any of the following commands for varying level of detail:
   • smartthings capabilities --help,
   • smartthings capabilities:presentation --help
   • smartthings capabilities:presentation:create --help
2. The CLI accepts data in YAML or JSON format and can output data in either format as well as the default table format.
3. Commands that take input accept stdin or a file specified by the --input (shortcut -i) flag.
4. Commands that output data will output the data to stdout unless a file is specified the using --output (shortcut -o) flag.
5. When no output format is specified, the CLI outputs a summary of the most useful information in table format. For full details, use --json (-j) or --yaml (-y).
6. When a command takes input and results in output, the format of the output will match the input format unless an output filename is specified using --output with a different extension.
7. Command line flags must go after the command. Use smartthings command -f flag instead of smartthings -f flag command.
8. You can open an issue to report a bug or ask a question.

Commands

Commands that use the SmartThings REST API are organized in topics that map to the API spec.

More information can be found using the --help flag with any command. For example, to find details on the edge:channels:create command, run:

smartthings edge:channels:create --help

| Command | Description | | -- | -- | | apps [id-or-index] | get a specific app or a list of apps | | apps:authorize | authorize calls to your AWS Lambda function from SmartThings | | apps:create | create an app | | apps:delete [id] | delete an app | | apps:oauth [id-or-index] | get OAuth information for an app | | apps:oauth:generate [id] | regenerate the OAuth clientId and clientSecret of an app | | apps:oauth:update [id] | update the OAuth settings of an app | | apps:register [id] | send request to app target URL to confirm existence and authorize lifecycle events | | apps:settings [id-or-index] | get the settings of an app | | apps:settings:update [id] | update the settings of an app | | apps:update [id] | update the settings of the app | | capabilities [id-or-index] | get a specific capability or a list of capabilities | | capabilities:create | create a capability | | capabilities:delete [id] | delete a capability | | capabilities:update [id] | update a capability | | capabilities:namespaces | list all capability namespaces currently available in a user account | | capabilities:presentation [id-or-index] | get presentation information for a specific capability | | capabilities:presentation:create [id] | create presentation model for a capability | | capabilities:presentation:update [id] | update presentation information of a capability | | capabilities:translations [id-or-index] [tag] | get list of locales supported by the capability | | capabilities:translations:create [id] | create a capability translation | | capabilities:translations:update [id] | update a capability translation | | capabilities:translations:upsert [id] | create or update a capability translation | | config [name] | list profiles defined in config file | | config:reset | clear saved answers to questions | | devicepreferences [id-or-index] | list device preferences or get information for a specific device preference | | devicepreferences:create | create a device preference | | devicepreferences:update [id] | update a device preference | | devicepreferences:translations [preferenceIdOrIndex] [tag] | list locales translated for a device preference or display translations for a specific locale | | devicepreferences:translations:create [device-preference-id] | create a translation for a device preference | | devicepreferences:translations:update [id] | update a device preference translation | | deviceprofiles [id-or-index] | get a specific device profile or a list device profiles | | deviceprofiles:create | create a new device profile | | deviceprofiles:delete [id] | delete a device profile | | deviceprofiles:device-config [id-or-index] | get the device configuration associated with a device profile | | deviceprofiles:presentation [id-or-index] | get the presentation associated with a device profile | | deviceprofiles:publish [id] | publish a device profile (published profiles cannot be modified) | | deviceprofiles:view [id-or-index] | show device profile and device configuration in a single, consolidated view | | deviceprofiles:translations [profileIdOrIndex] [tag] | list locales translated for a device profile or display translations for a specific locale | | deviceprofiles:translations:delete [id] [tag] | delete a device profile translation | | deviceprofiles:translations:upsert [id] | create or update a device profile translation | | deviceprofiles:update [id-or-index] | update a device profile | | deviceprofiles:view:create | create a new device profile and device configuration | | deviceprofiles:view:update [id] | update a device profile and its device configuration | | devices [id-or-index] | get a list of devices or details of a specific device | | devices:capability-status [device-id-or-index] [component-id] [capability-id] | get the current status of all of a device capability's attributes | | devices:component-status [device-id-or-index] [component-id] | get the current status of a device component's attributes | | devices:commands [id] [command] | execute a device command | | devices:delete [id] | delete a device | | devices:health [id-or-index] | get the current health status of a device | | devices:history [id-or-index] | get device history by device | | devices:preferences [id-or-index] | get the current preferences of a device | | devices:presentation [id-or-index] | get a device presentation | | devices:rename [id] [new-label] | rename a device | | devices:status [id-or-index] | get the current status of all of a device's component's attributes | | devices:update [id] | update a device's label and room | | edge | edge-specific commands | | edge:channels [id-or-index] | list all channels owned by you or retrieve a single channel | | edge:channels:assign [driver-id] [driver-version] | assign a driver to a channel | | edge:channels:create | create a channel | | edge:channels:delete [id] | delete a channel | | edge:channels:drivers [id-or-index] | list drivers assigned to a given channel | | edge:channels:enroll [hub-id] | enroll a hub in a channel | | edge:channels:enrollments [id-or-index] | list all channels a given hub is enrolled in | | edge:channels:invites [id-or-index] | list invitations or retrieve a single invitation by id or index | | edge:channels:invites:accept | accept a channel invitation | | edge:channels:invites:create | create an invitation | | edge:channels:invites:delete [id] | delete a channel invitation | | edge:channels:metainfo [driver-id-or-index] | display metadata about drivers assigned to channels | | edge:channels:unassign [driver-id] | remove a driver from a channel | | edge:channels:unenroll [hub-id] | unenroll a hub from a channel | | edge:channels:update [id] | update a channel | | edge:drivers [id-or-index] | list all drivers owned by you or retrieve a single driver | | edge:drivers:default [id-or-index] | list default drivers available to all users | | edge:drivers:delete [id] | delete an edge driver | | edge:drivers:devices [id-or-index] | list devices using edge drivers | | edge:drivers:install [driver] | install an edge driver onto a hub | | edge:drivers:installed [id-or-index] | list all drivers installed on a given hub | | edge:drivers:logcat [driver-id] | stream logs from installed drivers, simple temporary hard-coded version | | edge:drivers:package [project-directory] | build and upload an edge package | | edge:drivers:prune | uninstall unused edge drivers from a hub | | edge:drivers:switch [device-id] | change the driver used by an installed device | | edge:drivers:uninstall [driver-id] | uninstall an edge driver from a hub | | installedapps [id-or-index] | get a specific installed app or a list of installed apps | | installedapps:delete [id] | delete an installed app | | installedapps:rename [id] [new-name] | rename an installed app instance | | installedschema [id-or-index] | get a specific installed schema app or list installed schema apps | | installedschema:delete [id] | delete an installed Schema App | | invites:schema [id-or-index] | list invitations for a schema app or display details for an invitation | | invites:schema:create | create an invitation to a schema app | | invites:schema:delete [id] | delete a Schema App invitation | | locations [id-or-index] | list locations or get information for a specific location | | locations:create | create a location for a user | | locations:delete [id] | delete a location | | locations:history [id-or-index] | get history by location | | locations:update [id] | update a location | | locations:modes [id-or-index] | list modes or get information for a specific mode | | locations:modes:create | create a mode | | locations:modes:delete [id] | delete a mode | | locations:modes:update [id] | update a mode's label | | locations:modes:getcurrent [id] | get details of current mode | | locations:modes:setcurrent [id] | set the current mode | | locations:rooms [id-or-index] | list rooms or get information for a specific room | | locations:rooms:create | create a room | | locations:rooms:delete [id] | delete a room | | locations:rooms:update [id] | update a room | | logout | force login next time the specified (or default) profile is used | | organizations [id-or-index] | get a specific organization or list organizations the user belongs to | | organizations:current | get the currently active organization | | presentation [manufacturer-name] | query device presentation by presentation id | | presentation:device-config [manufacturer-name] | query device config by presentation id | | presentation:device-config:create | create a device config | | presentation:device-config:generate | generate the default device configuration | | rules [id-or-index] | get a specific rule or a list of rules | | rules:create | create a rule | | rules:delete [id] | delete a rule | | rules:execute [id] | execute a rule | | rules:update [id] | update a rule | | scenes [id-or-index] | list scenes or get information for a specific scene | | scenes:execute [id] | execute a scene | | schema [id-or-index] | list all Schema App links currently available in a user account | | schema:authorize | authorize calls to your Schema App AWS Lambda function from SmartThings | | schema:create | link Schema App to SmartThings | | schema:delete [id] | unlink a Schema App from smartthings | | schema:regenerate [id] | regenerate the client id and secret of the Schema App link | | schema:update [id] | update a link to a Schema App | | virtualdevices [id-or-index] | list all virtual devices available in a user account or retrieve a single device | | virtualdevices:create | create a virtual device from a device profile id or definition | | virtualdevices:create-standard | create a virtual device from one of the standard prototypes | | virtualdevices:delete [id] | delete a virtual device | | virtualdevices:events [device-id] [name] [value] [unit] | create events for a virtual device | | virtualdevices:update [id] | update a virtual device's label and room |

Configuration and Logging

Enable Debug Logging

Debug logging can be enabled via the SMARTTHINGS_DEBUG environment variable. This will log at debug level to the console as well as the default log file.

$ SMARTTHINGS_DEBUG=true smartthings <command>

More details about advanced configuration and logging in the CLI can be found on the configuration documentation page.