Get Started With the SmartThings CLI

tip

Find the SmartThings CLI source in our Community 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.

Advanced Configuration and Logging

The default CLI configuration can be overridden by creating a YAML file called config.yaml in the following location:

• $HOME/.config/@smartthings/cli on MacOS or Linux
• %LOCALAPPDATA%\@smartthings\cli on Windows

Profiles

You can define multiple profiles with different configurations. Top-level keys other than the special logging key define these profiles.

The default profile is named "default" and will be used unless otherwise specified. Most users can put their configuration options here.

To choose a different profile, you can either set the SMARTTHINGS_PROFILE environment variable, or use the --profile (-p) command line argument (when both are used, the command line argument overrides the environment variable.)

Configuration Options

The following per-profile config options are supported:

Option	Default Value	Description
indent	2	Indent level for JSON or YAML output.
groupTableOutputRows	true	Separate groups of four rows by a line to make long rows easier to follow across the screen.
organization	none	UUID of the organization to use in applicable CLI commands.
token	none	Use a bearer token (such as a PAT) for authentication instead of the default login flow.

Example

default:
  indent: 4
  groupTableOutputRows: true

tight:
  indent: 1
  groupTableOutputRows: false

Logging

Logging is useful when you are developing the CLI itself (rather than using it).

The CLI uses log4js for logging.

Logging is configured using a YAML file called logging.yaml in the same location as the config file mentioned above. The contents of this file are passed directly to log4js, so any valid log4js configuration can be included here. The following categories are used in the CLI:

• cli - Generic logger used by the CLI. Log entries will have the command name appended. (ex. cli.DriversCommand)
• rest-client - Used for the SDK that interfaces with the SmartThings API.
• login-authenticator - Used in the default OAuth login flow.