gem-hunter

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.

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.
2. 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.22.1 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

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

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

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.

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

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.

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

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.