Command line Switch

The command_line switch platform issues specific commands when it is turned on and off. This might very well become our most powerful platform as it allows anyone to integrate any type of switch into Home Assistant that can be controlled from the command line, including calling other scripts!

To enable it, add the following lines to your configuration.yaml:

# Example configuration.yaml entry
  - platform: command_line
        command_on: switch_command on kitchen
        command_off: switch_command off kitchen

Configuration Variables

switches map Required

The array that contains all command switches.

identifier map Required

Name of the command switch as slug. Multiple entries are possible.

command_on string Required

The action to take for on.

command_off string Required

The action to take for off.

command_state string (Optional)

If given, this command will be run. Returning a result code 0 will indicate that the switch is on.

value_template string (Optional)

If specified, command_state will ignore the result code of the command but the template evaluating to true will indicate the switch is on.

friendly_name string (Optional)

The name used to display the switch in the frontend.

icon_template template (Optional)

Defines a template for the icon of the entity.

command_timeout integer (Optional, default: 15)

Defines number of seconds for command timeout.

unique_id string (Optional)

An ID that uniquely identifies this switch. Set this to a unique value to allow customization through the UI.

A note on friendly_name:

When set, the friendly_name had been previously used for API calls and backend configuration instead of the object_id (“identifier”), but this behavior is changing to make the friendly_name for display purposes only. This allows users to set an identifier that emphasizes uniqueness and predictability for API and configuration purposes but have a prettier friendly_name still show up in the UI. As an additional benefit, if a user wanted to change the friendly_name / display name (e.g., from “Kitchen Lightswitch” to “Kitchen Switch” or “Living Room Light”, or remove the friendly_name altogether), they could do so without needing to change existing automations or API calls. See aREST device below for an example.


In this section you find some real-life examples of how to use this switch.

Change the icon when a state changes

This example demonstrates how to use template to change the icon as its state changes. This icon is referencing its own state.

  - platform: command_line

        friendly_name: Driveway buiten sensor
        command_on: >
          curl -X PUT -d '{"on":true}' "http://ip_address/api/sensors/27/config/"
        command_off: >
          curl -X PUT -d '{"on":false}' "http://ip_address/api/sensors/27/config/"
        command_state: curl http://ip_address/api/sensors/27/
        value_template: >
        icon_template: >
          {% if value_json.config.on == true %} mdi:toggle-switch
          {% else %} mdi:toggle-switch-off
          {% endif %}

aREST device

The example below is doing the same as the aREST switch. The command line tool curl is used to toggle a pin which is controllable through REST.

# Example configuration.yaml entry
  - platform: command_line
        command_on: "/usr/bin/curl -X GET"
        command_off: "/usr/bin/curl -X GET"
        command_state: "/usr/bin/curl -X GET"
        value_template: '{{ value == "1" }}'
        friendly_name: Kitchen Lightswitch

Given this example, in the UI one would see the friendly_name of “Kitchen Light”. However, the identifier is arest_pin_four, making the entity_id switch.arest_pin_four, which is what one would use in automation or in API calls.

Shutdown your local host

This switch will shutdown your system that is hosting Home Assistant.

This switch will shutdown your host immediately, there will be no confirmation.
# Example configuration.yaml entry
  - platform: command_line
        command_off: "/usr/sbin/poweroff"

Control your VLC player

This switch will control a local VLC media player (Source).

# Example configuration.yaml entry
  - platform: command_line
        command_on: "cvlc 1.mp3 vlc://quit &"
        command_off: "pkill vlc"

Control Foscam Motion Sensor

This switch will control the motion sensor of Foscam Webcams which Support CGI Commands (Source). This switch supports statecmd, which checks the current state of motion detection.

# Example configuration.yaml entry
  - platform: command_line
        command_on: 'curl -k "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig&isEnable=1&usr=admin&pwd=password"'
        command_off: 'curl -k "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig&isEnable=0&usr=admin&pwd=password"'
        command_state: 'curl -k --silent "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=getMotionDetectConfig&usr=admin&pwd=password" | grep -oP "(?<=isEnable>).*?(?=</isEnable>)"'
        value_template: '{{ value == "1" }}'
  • Replace admin and password with an “Admin” privileged Foscam user
  • Replace ipaddress with the local IP address of your Foscam