The SmartThings Unified CLI is in an alpha release and is considered a work in progress.
- Find the SmartThings Unified CLI source in our GitHub repo.
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
- Download the appropriate binary from the releases tab of the CLI GitHub page.
- Install it on your path and rename it to "smartthings". It does not need administrator privileges, but must be executable.
smartthings --helpto make sure it's working.
- Run a specific command with
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:
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.
|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 |
- You can get more specific information about any command or sub-hierarchy of commands by using
--helpwith 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
- Commands that output data will output the data to stdout unless a file
is specified the using
- 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
--outputwith a different extension.
Visit the Commands section of the SmartThings CLI repo
README for a full list of commands.
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
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:
- Be sure you're using at least NodeJS version 12.
- In the root directory of the SDK
npm link. If you're using a globally-installed version of node, you might need to run this with admin privileges.
- Install Lerna globally with
npm -g i lerna. (Alternatively, you can use
npx lernabelow instead of simply
- In the in the root directory of the CLI repository run
./bootstrap.sh --reset --link-sdk.
- The bootstrap script will compile the CLI but you can:
lerna run compileto compile again, or
lerna run watchto watch for changes and compile on the fly, or
lerna run buildto clean and compile
- To run the CLI, run the
runcommand 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:
- Run eslint via
lerna run lint
- Run tests with
lerna run test
- 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 buildwill do this, but you can also run
lerna run readme.