Get Started With the SmartThings CLI

tip

Find the SmartThings CLI source in our GitHub repo.

Usage

Installation

Homebrew (macOS)

brew install smartthingscommunity/smartthings/smartthings

Windows

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

caution

The Windows installer may display a warning titled “Windows protected your PC”. To run the installation when this warning shows, click “More info”, then click the “Run anyway” button.

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.

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

Authentication

The CLI supports an automatic login flow that launches a browser window prompting you to log in with your Samsung account and grant the CLI permission to access your account.

Personal Access Tokens (PATs)

important

We generally don't recommend this approach since it is less secure, given that PATs don't expire unless revoked by the user. However, it can be necessary for some use cases such as working with headless servers.

You can use a personal access token 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:

default:
  token: my-personal-access-token

Input and Output Considerations

Many commands in the CLI handle complex input and/or output, mostly for use with the SmartThings REST API. 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.

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.

Helpful Hints

• 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
• The CLI accepts data in YAML or JSON format and can output data in either format as well as the default table format.
• Commands that take input accept stdin or a file specified by the --input (shortcut -i) flag.
• Commands that output data will output the data to stdout unless a file is specified the using --output (shortcut -o) flag.
• 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.

Commands

Visit the Commands section of the SmartThings CLI repo README for a full list of commands.

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>

Developing the CLI

If you are interested in contributing to the SmartThing CLI, please read the contributing document in the SmartThings CLI repo.