LightStudio CLI

LightStudio interface is a desktop application that you can install and creating lights, scenes, but all these interactions are stored in database via "LightStudio CLI", which can be used both as a command line tool to create, or it can lift HTTP server so LightStudio desktop interface or other thirdparties can work with the api.

In this document you will learn how to use lightstudio cli.

Note: LightStudio CLI is being automatically installed with the software bundle, and registered as system service upon installation, should be available in your terminal using lightstudio [...command].

Run LightStudio CLI

You need to download the binary of LightStudio CLI, and then put it in an appropriate location and you can name it lightstudio and call it.

lightstudio

It will print:

NAME:
   LightStudio API, Webserver and Commandline - You can create light, change their status and couple of more using this API

USAGE:
    [global options] command [command options] [arguments...]

COMMANDS:
   version, v  Shows the version of the CLI
   light, l    Actions to the specific light.
   server, s   Starts the lightstudio api http server for the UI to use.
   help, h     Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help

Check the version

Basic usage is to understand the cli installed version (Without --)

lightstudio version

Create a new light

You can use the CLI to create a new light, only by providing a name:

go run cmd/cli/cli.go light create --name "Sample Light for Docs"

It will create a light in the database, now you can get it via list command.

Listing the lights

go run cmd/cli/cli.go light list

It will format the result of list in a table so you can read it more clearly.

+---+--------------------------------------+-----------------------+-------+-----+------------+------------+
| # | UniqueId                             | Name                  | Power | Hue | Saturation | Brightness |
+---+--------------------------------------+-----------------------+-------+-----+------------+------------+
| 1 | e2821084-c43f-48d4-b5fb-76efba256a27 | Sample Light for Docs | false | 0   | 0          | 0          |
+---+--------------------------------------+-----------------------+-------+-----+------------+------------+

You see that there are parameters called power, hue, saturation, brightness. By default, a light is turned off.

When you create any entity across the project (light, scenario, timeline, etc...) a unique string will be assigned to them automatically and it will be used as primary key, or unique way to communicate with this light.

Note: Power = false means electrically off, you cannot set HSB paramters to zero and expected device will be off.

Setting color parameters, and control power.

If you want to make any change to any lights you can use light set command. These are the variables you can modify:

OPTIONS:
   --id value     string unique id of the light
   --power value  0 to set off, and 1 to set on (default: 0)
   --hue value    the amount of hue (default: 0)
   -s value       the amount of saturation (default: 0)
   -b value       the amount of brightness (default: 0)
   --name value   set the name of the light to user interface

Turn on/off the light

You can change the power by setting 0 or 1 in CLI, you need to provide --id of that light (long string) and --power number.

go run cmd/cli/cli.go light set --power 1 --id "e2821084-c43f-48d4-b5fb-76efba256a27"

If you get the light of lights, you will see the power is turned on on this specific light.

+---+--------------------------------------+-----------------------+-------+-----+------------+------------+
| # | UniqueId                             | Name                  | Power | Hue | Saturation | Brightness |
+---+--------------------------------------+-----------------------+-------+-----+------------+------------+
| 1 | e2821084-c43f-48d4-b5fb-76efba256a27 | Sample Light for Docs | true  | 0   | 0          | 0          |
+---+--------------------------------------+-----------------------+-------+-----+------------+------------+

Hue, Satration and Brightness

Respectively, you can set the hue, saturation (via -s) and brightness (via -b), also possible to change the name of the light.

go run cmd/cli/cli.go light set --power 1 --id "e2821084-c43f-48d4-b5fb-76efba256a27" -s 10 -b 20 -hue 30 --name "Updated Light 2"

and it would result into:

+---+--------------------------------------+-----------------+-------+-----+------------+------------+
| # | UniqueId                             | Name            | Power | Hue | Saturation | Brightness |
+---+--------------------------------------+-----------------+-------+-----+------------+------------+
| 1 | e2821084-c43f-48d4-b5fb-76efba256a27 | Updated Light 2 | true  | 30  | 10         | 20         |
+---+--------------------------------------+-----------------+-------+-----+------------+------------+

Deleting a light

You can delete a light from system if you need, and all data related to this light is going to be removed, and if it's binded to thirdparty, (such as Philips Hue) those bindings will be revoked.

go run cmd/cli/cli.go light delete --id "e2821084-c43f-48d4-b5fb-76efba256a27"

Count the lights

You can count the total lights available in the database, instead of gettings users list.

go run cmd/cli/cli.go light count

It will print something similar to:

Total lights in the system: 1