Skip to main content

Get Started

note

The SmartThings Unified CLI is in an alpha release and is considered a work in progress.

tip
  • Find the SmartThings Unified CLI source in our GitHub repo.

Build Information#

The SmartThings CLI uses Lerna to manage multiple packages in a monorepo. The following packages are included in the SmartThings CLI repo:

  • cli - the CLI itself; @smartthings/cli node package
  • lib - a library for use in the CLI and its extensions; @smartthings/cli-lib node package
  • testlib - a library for use in the CLI and its extensions with utility methods to make testing with Jest easier; @smartthings/cli-testlib node package

Usage#

  1. Download the appropriate binary from the releases tab of the CLI GitHub page.
  2. Install it on your path and rename it to "smartthings". It does not need administrator privileges, but must be executable.
  3. Run smartthings --help to make sure it's working.
  4. 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.

Although not recommended, you can use use a personal access token for authentication 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.

NameShortcutDescription
jsonjWrite output in JSON format.
yamlyWrite output in YAML format.
indentSpecify the number of spaces for YAML or JSON output
inputiSpecify a filename for input.
outputoSpecify 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.

Developing the CLI#

The SmartThings CLI uses Lerna to manage multiple packages in a monorepo. Dependencies are hoisted during bootstrap by default. To disable this, modify the following in lerna.json.

"command": {
"bootstrap": {
"hoist": false
}

Using a Pre-Release Version#

The CLI depends on the SmartThings Core SDK. To use a pre-release version for testing purposes, you will need to make any required changes in both checked-out repositories (SDK and CLI). Then:

  1. Be sure you're using at least NodeJS version 12.
  2. In the root directory of the SDK
    1. run npm install.
    2. run npm link. If you're using a globally-installed version of node, you might need to run this with admin privileges.
  3. Install Lerna globally with npm -g i lerna. (Alternatively, you can use npx lerna below instead of simply lerna.)
  4. In the in the root directory of the CLI repository run ./bootstrap.sh --reset --link-sdk.
  5. The bootstrap script will compile the CLI but you can:
    1. run lerna run compile to compile again, or
    2. run lerna run watch to watch for changes and compile on the fly, or
    3. run lerna run build to clean and compile
  6. To run the CLI, run the run command in packages/cli/bin. You can create a link to this file to make it easier to run. Since the final installed name will be "smartthings", that's a good name for the link. For example: ln -s ~/mydevdir/smartthings-cli/packages/cli/bin/run ~/bin/smartthings

There is also a full_clean.sh script you can run to start over again. This can be helpful when pulling new code.

Before opening a pull request be sure to:

  1. Run eslint via lerna run lint
  2. Run tests with lerna run test
  3. If you've added or or removed commands or updated any of their arguments or flags, be sure to update the readme. Doing a full build via lerna run build will do this, but you can also run lerna run readme.