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.

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.
  --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.
  --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.
  turn-on-behavior  Modify bulb turn-on behavior.
  usage             Query usage for historical consumption.
  wifi              Commands to control wifi settings.