@smartthings/cli

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)

• Download the appropriate zipped binary from the latest Release.
• 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

• Run smartthings --help to get more information on each command.
• 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

• 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 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).
• 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.
• Command line flags must go after the command. Use smartthings command -f flag instead of smartthings -f flag command.
• 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.