Install
Download the latest release And extract it in a location for execution.
The shade executable is located in the bin/ folder.
Add it to your $PATH or execute it directly.
Shade's CLI provides a cross-platform terminal utility for controlling hue devices.
Download the latest release And extract it in a location for execution.
The shade executable is located in the bin/ folder.
Add it to your $PATH or execute it directly.
Confirm the cli executes correctly by running the
base --help command.
$ shade --help
Usage: main [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help Show this message and exit
Commands:
(...)The discovery process uses Hue's API to find Hue Bridges on the local network. This is the only command in the CLI that requires an internet connection, and is only used to find bridges. If you know the IP address of the hue bridge that you want to connect to, this step can be skipped.
Request a list of local devices on the network with the
discover command:
$ shade discover
001878fffe321a4a:
ip: 192.168.1.23
port: 443
Shade is configured to use HTTPS by default when connecting to the hue bridge. However, since connections are done on a local network, the SSL certificate from the hue bridge must be trusted on your system before establishing a connection.
For each command, you have the option to specify a security scheme used for the HTTP connections.
Platform trust is the default trust strategy for Shade. This will defer validation of the HTTPS connection to your platform, meaning you will have to manually install or mark the certificate as trusted on your system in order to connect to the hue bridge.
This option requires no configuration within Shade. However, it requires that the certificate be manually trusted in your system.
If you trust the network that your commands are running on,
you can ignore the SSL connection with the --insecure
flag when running commands.
For security reasons it is not recommended that you use an insecure connection unless you are on a trusted network.
The hue bridge is
configured
to use a custom CA in its HTTPS certificates. You can configure
Shade to trust this root certificate manually, by specifying
the IP and device ID of the bridge that were obtained during
discovery in the
Properties File
located in your home directory: $HOME/.shade-cli.properties
hostname=01234xxabcdef
security=hue
ip=192.168.1.5
To request an authorization token, call the authorize
command.
$ shade authorize --host=192.168.1.23
Press button on hue bridge to complete
Application Key: ********
Client Key: ********The command will wait for the button on the hue bridge to be pressed in order to confirm the authorization before providing the keys.
Requests made with the CLI require an api key and host specified or configured. You can specify these properties per-command or in a configuration file
For any command you can specify the host and
key options explicitly.
(The authorize command does not need a
key specified, and the discover command
needs neither a key nor host)
$ shade list-lights --host=192.168.1.23 --key=*********
If your bridge does not support SSL connections, you may
disable https verification with the --insecure
flag:
$ shade list-lights --insecure --host=192.168.1.23 --key=*********
You can also specify the configuration via a file located in
your home directory: $HOME/.shade-cli.properties
Set an application and client key with the following properties:
hostname=192.168.1.23
application_key=********
client_key=********
security=platformYou can control lights with the following commands:
list-lights To get a list of all lights on the
hue bridge.
get-light To get information about a specific
light.
update-light to change the state or info
for a specific light.
You can control rooms with the following commands:
list-rooms To get a list of all rooms on the
Hue bridge.
get-room To get info about a specific room.
update-room To change info for a specific room.
create-room To create a new room on the Hue bridge.
delete-room To remove a room from the Hue bridge.
You can control zones with the following commands:
list-zones To get a list of all zones on the
Hue bridge.
get-zone To get information for a specific zone.
update-zone To update the configuration of a zone.
create-zone To create a new zone configuration.
delete-zone To remove a zone configuration.
You can control grouped lights with the following commands:
list-grouped-lights To get a list of all grouped
lights configured on the Hue bridge.
get-grouped-light To get information for a single
grouped light.
update-grouped-light To update the state of a
light group.
You can get/update information for devices with the following commands:
list-devices To get a list of all devices
connected to the Hue bridge.
get-device To get information for a single device.
update-device To update the configuration of a
device.
identify-device To trigger a visual identification
sequence on a device.
delete-device To remove a device from the Bridge.
You can get information about bride api resources with the following commands:
list-resources To get a list of all resources
available on the Hue bridge.
You can control scenes with the following commands:
list-scenes To get a list of all scenes configured
on the Hue bridge.
get-scene To get information for a single scene.
update-scene To update the configuration of a
specified scene.
create-scene To create a new scene.
delete-scene To remove a scene from the Hue bridge.