Command Line Interface for the SmartThings APIs
npm install @smartthings/cli
!npm
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
Note that the MacOS binaries require at least MacOS 13.5.
``console`
brew install smartthingscommunity/smartthings/smartthings
Download and run the smartthings.msi installer from the latest Release.
1. Download the appropriate zipped binary from the latest Release.
1. Extract and install it on your system path. It does not need administrator privileges but will need to be executable.
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.
`console`
npm install --global @smartthings/cli
Run smartthings --version and verify the version matches the latest release.
1. Run smartthings --help to get more information on each command.smartthings
1. Run a specific command with .
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. |
On MacOS with zsh, run smartthings generate-completions-script >> ~/.zshrc. Note that.zprofile
when running this command, a comment suggests adding to 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
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 flag to commands or by creating atoken
configuration file
and including the token in a 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.
1. You can get more specific information about any command or sub-hierarchy
of commands by using --help with a specific command or branch. Forsmartthings capabilities --help
example, you can run any of the following commands for varying level of
detail:
* ,smartthings capabilities:presentation --help
*
*
1. The CLI accepts data in YAML or JSON format and can
output data in either format as well as the default table format.
1. Commands that take input accept stdin or a file specified
by the (shortcut -i) flag.--output
1. Commands that output data will output the data to stdout unless a file
is specified the using (shortcut -o) flag.--json
1. When no output format is specified, the CLI outputs a summary of the most useful information
in table format. For full details, use (-j) or --yaml (-y).--output
1. 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 with a different extension.smartthings command -f flag
1. Command line flags must go after the command. Use insteadsmartthings -f flag command
of .
1. You can open an issue to report a bug or ask a question.
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 findedge:channels:create
details on the command, run:
`console`
smartthings edge:channels:create --help
| Command | Description |
| -- | -- |
| apps [id-or-index] | get a specific app or a list of apps |
| apps:authorize
| 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
| 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
| presentation:device-config
| presentation:device-config:create | create a device config |
| presentation:device-config:generate
| 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
| 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 |
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.
`console``
$ SMARTTHINGS_DEBUG=true smartthings
More details about advanced configuration and logging in the CLI can be found on the
configuration documentation page.