Command line

The Command line integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] offers functionality that issues specific commands to get data or to control a device.

Using templates

For incoming data, a value template translates incoming JSON or raw data to a valid payload. Incoming payloads are rendered with possible JSON values, so when rendering, the value_json can be used to access the attributes in a JSON based payload, otherwise the value variable can be used for non-json based data.

Additional, the this can be used as variables in the template. The this attribute refers to the current entity state of the entity. Further information about this variable can be found in the template documentation

{ "state": "ON", "temperature": 21.902 }

Binary sensor

To use your Command binary sensor in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
command_line:
  - binary_sensor:
      command: "cat /proc/sys/net/ipv4/ip_forward"
  - binary_sensor:
      command: "echo 1"

Cover

A command_linecover platform that issues specific commands when it is moved up, down and stopped. It allows anyone to integrate any type of cover into Home Assistant that can be controlled from the command line.

To enable a command line cover in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
command_line:
  - cover:
      command_open: move_command up garage
      command_close: move_command down garage
      command_stop: move_command stop garage
      name: Garage

Notify

The command_line platform allows you to use external tools for notifications from Home Assistant. The message will be passed in as STDIN.

To enable those notifications in your installation, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
command_line:
  - notify:
      command: "espeak -vmb/mb-us1"

To use notifications, please see the getting started with automation page.

Sensor

To enable it, add the following lines to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

# Example configuration.yaml entry
command_line:
  - sensor:
      command: SENSOR_COMMAND
  - sensor:
      command: SENSOR_COMMAND_2

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.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

# Example configuration.yaml entry
command_line:
  - switch:
      name: Kitchen Light
      command_on: switch_command on kitchen
      command_off: switch_command off kitchen

Execution

The command is executed within the configuration directory.

With a 0 exit code, the output (stdout) of the command is used as value. In case a command results in a non 0 exit code or is terminated by the command_timeout, the result is only logged to Home Assistant log and the sensors value is not updated.

Examples binary sensor platform

In this section you find some real-life examples of how to use the command_line sensor.

SickRage

Check the state of an SickRage instance.

# Example configuration.yaml entry
command_line:
  - binary_sensor:
      command: 'netstat -na | find "33322" | find /c "LISTENING" > nul && (echo "Running") || (echo "Not running")'
      name: "sickragerunning"
      device_class: moving
      payload_on: "Running"
      payload_off: "Not running"

Check RasPlex

Check if RasPlex is online.

command_line:
  - binary_sensor:
      command: 'ping -c 1 rasplex.local | grep "1 received" | wc -l'
      name: "is_rasplex_online"
      device_class: connectivity
      payload_on: 1
      payload_off: 0

An alternative solution could look like this:

command_line:
  - binary_sensor:
      name: Printer
      command: 'ping -W 1 -c 1 192.168.1.10 > /dev/null 2>&1 && echo success || echo fail'
      device_class: connectivity
      payload_on: "success"
      payload_off: "fail"

Consider to use the ping sensor as an alternative to the samples above.

Check if a system service is running

The services running is listed in /etc/systemd/system and can be checked with the systemctl command:

$ systemctl is-active home-assistant@rock64.service
active
$ sudo service home-assistant@rock64.service stop
$ systemctl is-active home-assistant@rock64.service
inactive

A binary command line sensor can check this:

command_line:
  - binary_sensor:
      command: '/bin/systemctl is-active home-assistant@rock64.service'
      payload_on: "active"
      payload_off: "inactive"

Example cover platform

# Example configuration.yaml entry
command_line:
  - cover:
      name: Garage door
      command_open: move_command up garage
      command_close: move_command down garage
      command_stop: move_command stop garage
      command_state: state_command garage
      value_template: >
        {% if value == 'open' %}
        100
        {% elif value == 'closed' %}
        0
        {% endif %}

Examples sensor platform

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

CPU temperature

Thanks to the proc file system, various details about a system can be retrieved. Here the CPU temperature is of interest. Add something similar to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
command_line:
  - sensor:
      name: CPU Temperature
      command: "cat /sys/class/thermal/thermal_zone0/temp"
      # If errors occur, make sure configuration file is encoded as UTF-8
      unit_of_measurement: "°C"
      value_template: "{{ value | multiply(0.001) | round(1) }}"

Monitoring failed login attempts on Home Assistant

If you’d like to know how many failed login attempts are made to Home Assistant, add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
command_line:
  - sensor:
      name: Badlogin
      command: "grep -c 'Login attempt' /home/hass/.homeassistant/home-assistant.log"

Make sure to configure the Logger integration to monitor the HTTP integration at least the warning level.

# Example working logger settings that works
logger:
  default: critical
  logs:
    homeassistant.components.http: warning

Details about the upstream Home Assistant release

You can see directly in the frontend (Developer tools -> About) what release of Home Assistant you are running. The Home Assistant releases are available on the Python Package Index. This makes it possible to get the current release.

command_line:
  - sensor:
      command: python3 -c "import requests; print(requests.get('https://pypi.python.org/pypi/homeassistant/json').json()['info']['version'])"
      name: HA release

Read value out of a remote text file

If you own devices which are storing values in text files which are accessible over HTTP then you can use the same approach as shown in the previous section. Instead of looking at the JSON response we directly grab the sensor’s value.

command_line:
  - sensor:
      command: python3 -c "import requests; print(requests.get('http://remote-host/sensor_data.txt').text)"
      name: File value

Use an external script

The example is doing the same as the aREST sensor but with an external Python script. It should give you an idea about interfacing with devices which are exposing a RESTful API.

The one-line script to retrieve a value is shown below. Of course it would be possible to use this directly in the configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file but need extra care about the quotation marks.

python3 -c "import requests; print(requests.get('http://10.0.0.48/analog/2').json()['return_value'])"

The script (saved as arest-value.py) that is used looks like the example below.

#!/usr/bin/python3
from requests import get

response = get("http://10.0.0.48/analog/2")
print(response.json()["return_value"])

To use the script you need to add something like the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.

# Example configuration.yaml entry
command_line:
  - sensor:
      name: Brightness
      command: "python3 /path/to/script/arest-value.py"

Usage of templating in command:

Templates are supported in the command configuration variable. This could be used if you want to include the state of a specific sensor as an argument to your external script.

# Example configuration.yaml entry
command_line:
  - sensor:
      name: Wind direction
      command: "sh /home/pi/.homeassistant/scripts/wind_direction.sh {{ states('sensor.wind_direction') }}"
      unit_of_measurement: "Direction"

Usage of JSON attributes in command output

The example shows how you can retrieve multiple values with one sensor (where the additional values are attributes) by using value_json and json_attributes.

# Example configuration.yaml entry
command_line:
  - sensor:
      name: JSON time
      json_attributes:
        - date
        - milliseconds_since_epoch
      command: "python3 /home/pi/.homeassistant/scripts/datetime.py"
      value_template: "{{ value_json.time }}"

JSONPlaceholder provides sample JSON data for testing. In the below example, JSONPath locates the attributes in the JSON document. JSONPath Online Evaluator provides a tool to test your JSONPath.

command_line:
  - sensor:
      name: JSON user
      command: python3 -c "import requests; print(requests.get('https://jsonplaceholder.typicode.com/users').text)"
      json_attributes_path: "$.[0].address"
      json_attributes:
        - street
        - suite
        - city
        - zipcode
      value_template: "{{ value_json[0].name }}"

Example switch platform

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.

command_line:
  - switch:
      name: Driveway outside 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: >
        {{value_json.config.on}}
      icon: >
        {% 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
command_line:
  - switch:
      command_on: "/usr/bin/curl -X GET http://192.168.1.10/digital/4/1"
      command_off: "/usr/bin/curl -X GET http://192.168.1.10/digital/4/0"
      command_state: "/usr/bin/curl -X GET http://192.168.1.10/digital/4"
      value_template: '{{ value == "1" }}'
      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.

# Example configuration.yaml entry
command_line:
  - switch:
      name: Home Assistant System Shutdown
      command_off: "/usr/sbin/poweroff"

Control your VLC player

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

# Example configuration.yaml entry
command_line:
  - switch:
      name: VLC
      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
command_line:
  - switch:
      name: Foscam Motion
      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

Actions

Available actions: reload.

Action command_line.reload

Reload all command_line entities.

This action takes no data attributes.