Command-line usage

The package is shipped with a console tool named kasa, refer to kasa --help for detailed usage. The device to which the commands are sent is chosen by KASA_HOST environment variable or passing --host <address> as an option. To see what is being sent to and received from the device, specify option --debug.

To avoid discovering the devices when executing commands its type can be passed as an option (e.g., --type plug for plugs, --type bulb for bulbs, ..). If no type is manually given, its type will be discovered automatically which causes a short delay.

If no command is given, the state command will be executed to query the device state.

Note

Some commands (such as reading energy meter values, changing bulb settings, or accessing individual sockets on smart strips) additional parameters are required, which you can find by adding --help after the command, e.g. kasa --type emeter --help or kasa --type hsv --help. Refer to the device type specific documentation for more details.

Discovery

The tool can automatically discover supported devices using a broadcast-based discovery protocol. This works by sending an UDP datagram on port 9999 to the broadcast address (defaulting to 255.255.255.255).

On multihomed systems, you can use --target option to specify the broadcsat target. For example, if your devices reside in network 10.0.0.0/24 you can use kasa --target 10.0.0.255 discover to discover them.

Note

When no command is specified when invoking kasa, a discovery is performed and the state command is executed on each discovered device.

Provisioning

You can provision your device without any extra apps by using the kasa wifi command:

1. If the device is unprovisioned, connect to its open network

2. Use kasa discover (or check the routes) to locate the IP address of the device (likely 192.168.0.1, if unprovisioned)

3. Scan for available networks using kasa --host 192.168.0.1 wifi scan see which networks are visible to the device

4. Join/change the network using kasa --host 192.168.0.1 wifi join <network to join>

As with all other commands, you can also pass --help to both join and scan commands to see the available options.

kasa --help

Usage: kasa [OPTIONS] COMMAND [ARGS]...

  A tool for controlling TP-Link smart home devices.

Options:
  --host TEXT                     The host name or IP address of the device to
                                  connect to.
  --port INTEGER                  The port of the device to connect to.
  --alias TEXT                    The device name, or alias, of the device to
                                  connect to.
  --target TEXT                   The broadcast address to be used for
                                  discovery.  [default: 255.255.255.255]
  -d, --debug
  --type [plug|bulb|dimmer|strip|lightstrip]
  --json                          Output raw device response as JSON.
  --discovery-timeout INTEGER     Timeout for discovery.
  --username TEXT                 Username/email address to authenticate to
                                  device.
  --password TEXT                 Password to use to authenticate to device.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Commands:
  alias             Get or set the device (or plug) alias.
  brightness        Get or set brightness.
  discover          Discover devices in the network.
  effect            Set an effect.
  emeter            Query emeter for historical consumption.
  hsv               Get or set color in HSV.
  led               Get or set (Plug's) led state.
  off               Turn the device off.
  on                Turn the device on.
  presets           List and modify bulb setting presets.
  raw-command       Run a raw command on the device.
  reboot            Reboot the device.
  schedule          Scheduling commands.
  state             Print out device state and versions.
  sysinfo           Print out full system information.
  temperature       Get or set color temperature.
  time              Get the device time.
  toggle            Toggle the device on/off.
  turn-on-behavior  Modify bulb turn-on behavior.
  usage             Query usage for historical consumption.
  wifi              Commands to control wifi settings.