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. Note that the --type parameter only works for legacy devices using port 9999.

To avoid discovering the devices for newer KASA or TAPO devices using port 20002 for discovery the --device-family, -encrypt-type and optional -login-version options can be passed and the devices will probably require authentication via --username and --password. Refer to kasa --help for detailed usage.

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 ports 9999 and 20002 to the broadcast address (defaulting to 255.255.255.255).

Newer devices that respond on port 20002 will require TP-Link cloud credentials to be passed (unless they have never been connected to the TP-Link cloud) or they will report as having failed authentication when trying to query the device. Use --username and --password options to specify credentials. These values can also be set as environment variables via KASA_USERNAME and KASA_PASSWORD.

On multihomed systems, you can use --target option to specify the broadcast 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.

Note

For devices requiring authentication, the device-stored credentials can be changed using the update-credentials commands, for example, to match with other cloud-connected devices. However, note that communications with devices provisioned using this method will stop working when connected to the cloud.

Note

Some commands do not work if the device time is out-of-sync. You can use kasa time sync command to set the device time from the system where the command is run.

Warning

At least some devices (e.g., Tapo lights L530 and L900) are known to have a watchdog that reboots them every 10 minutes if they are unable to connect to the cloud. Although the communications are done locally, this will make these devices unavailable for a minute every time the device restarts. This does not affect other devices to our current knowledge, but you have been warned.

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]
  -v, --verbose                   Be more verbose on output
  -d, --debug                     Print debug output
  --type [plug|switch|bulb|dimmer|strip|lightstrip|smart|camera]
                                  The device type in order to bypass
                                  discovery. Use `smart` for newer devices
  --json / --no-json              Output raw device response as JSON.
  -e, --encrypt-type [KLAP|AES|XOR]
  -df, --device-family TEXT       Device family type, e.g. `SMART.KASASWITCH`.
                                  Deprecated use `--type smart`
  -lv, --login-version INTEGER    The login version for device authentication.
                                  Defaults to 2
  --https / --no-https            Set flag if the device encryption uses
                                  https.
  --timeout INTEGER               Timeout for device communications.
                                  [default: 5]
  --discovery-timeout INTEGER     Timeout for discovery.  [default: 10]
  --username TEXT                 Username/email address to authenticate to
                                  device.
  --password TEXT                 Password to use to authenticate to device.
  --credentials-hash TEXT         Hashed credentials used to authenticate to
                                  the device.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Subcommands:
  discover  Discover devices in the network.
  device    Commands to control basic device settings.
  feature   Access and modify features.
  light     Commands to control light settings.
  wifi      Commands to control wifi settings.
  time      Get and set time.
  schedule  Scheduling commands.
  usage     Query usage for historical consumption.

Common usage commands (also available under the `usage` subcommand):
  energy  Query energy module for historical...

Common device commands (also available under the `device` subcommand):
  state               Print out device state and versions.
  on                  Turn the device on.
  off                 Turn the device off.
  toggle              Toggle the device on/off.
  led                 Get or set (Plug's) led state.
  alias               Get or set the device (or plug) alias.
  reboot              Reboot the device.
  update_credentials  Update device credentials for...
  sysinfo             Print out full system information.

Common light commands (also available under the `light` subcommand):
  presets      List and modify bulb setting presets.
  brightness   Get or set brightness.
  hsv          Get or set color in HSV.
  temperature  Get or set color temperature.
  effect       Set an effect.