Photons from the command line

Photons provides the lifx command-line utility which can be used to perform several tasks. If multiple tasks are required, consider creating a script instead.

To access these tasks, ensure the lifx command is in your PATH by activating the virtual environment into which Photons is installed.

A simple example of running a task with the lifx utility:

$ lifx lan:transform match:label=kitchen -- '{"power": "off"}'

This command uses the lan target with the transform task to find a device with the label kitchen and powers it off.

The lifx utility uses the following command-line structure:

$ lifx <target>:<task> <reference> <artifact> -- <options>

Some tasks don’t need all of these items, like unpack doesn’t require a reference to be specified for example.

Photons includes a single lan target, which is configured to discover and communicate with devices on the local network using the default broadcast address of 255.255.255.255. It’s possible to change the default broadcast address used by the lan target or create new targets by providing a custom configuration.

To list all available tasks, run lifx help. To get details about a specific task, run lifx help <task>, e.g. lifx help transform.

Note

The options field must be valid JSON syntax which can be cumbersome to provide directly on the command line. For ease of use, the lifx utility accepts a file:// path instead:

$ lifx lan:transform -- file:///path/to/my/options.json

If the file is in the current directory:

$ lifx lan:transform -- file://options.json

Photons will output a lot of information by default which you can make go away with a --silent option or by setting PHOTONS_SILENT_BY_DEFAULT=1 in your environment where you are running photons commands. If that environment variable is set then you can override it with --unsilent.

Running CLI commands on Windows

Running the lifx utility from the Windows Command Prompt requires the JSON syntax to be escaped correctly, which can be challenging:

C:\Users\me> lifx lan:transform -- "{\"power\": \"on\"}"

An alternative method which doesn’t require escaping JSON is to write a simple Python script instead:

__import__("photons_core").run('lan:transform -- {"power": "on"}')

which can be run directly from the command prompt:

C:\Users\me> python power_on.py