Shell Command
This integration can expose regular shell commands as actions. Actions can be called from a script or in automation. Shell commands aren’t allowed for a camel-case naming, please use lowercase naming only and separate the names with underscores.
Note that the shell command process will be terminated after 60 seconds, full stop. There is no option to alter this behavior, this is by design because Home Assistant is not intended to manage long-running external processes.
Configuration
# Example configuration.yaml entry
# Exposes action shell_command.restart_pow
shell_command:
restart_pow: touch ~/.pow/restart.txt
The commands can be dynamic, using templates to insert values for arguments. When using templates, shell_command runs in a more secure environment which doesn’t allow any shell helpers like automatically expanding the home dir ~
or using pipe symbols to run multiple commands. Similarly, only content after the first space can be generated by a template. This means the command name itself cannot be generated by a template, but it must be literally provided.
Any action data passed into the action to activate the shell command will be available as a variable within the template.
stdout
and stderr
output from the command are both captured and will be logged by setting the log level to debug.
Execution
The command
is executed within the configuration directory.
If you are using Home Assistant Operating Systemhomeassistant
container context. So if you test or debug your script, it might make sense to do this in the context of this container to get the same runtime environment.
A 0
exit code means the commands completed successfully without error. In case a command results in a non 0
exit code or is terminated after a timeout of 60 seconds, the result is logged to Home Assistant log.
Response
Shell commands provide an action response in a dictionary containing stdout
, stderr
, and returncode
. These can be used in automations to act upon the command results using response_variable
.
Examples
Defining multiple shell commands
You can also define multiple shell commands at once. This is an example that defines three different (unrelated) shell commands.
# Example configuration.yaml entry
shell_command:
restart_pow: touch ~/.pow/restart.txt
call_remote: curl http://example.com/ping
my_script: bash /config/shell/script.sh
Automation example
This is an example of a shell command used in conjunction with an input helper and an automation.
# Apply value of a GUI slider to the shell_command
automation:
- alias: "run_set_ac"
triggers:
- trigger: state
entity_id: input_number.ac_temperature
actions:
- action: shell_command.set_ac_to_slider
input_number:
ac_temperature:
name: A/C Setting
initial: 24
min: 18
max: 32
step: 1
shell_command:
set_ac_to_slider: 'irsend SEND_ONCE DELONGHI AC_{{ states("input_number.ac_temperature") }}_AUTO'
The following example shows how the shell command response may be used in automations.
# Create a ToDo notification based on file contents
automation:
- alias: "run_set_ac"
triggers:
- ...
actions:
- action: shell_command.get_file_contents
data:
filename: "todo.txt"
response_variable: todo_response
- if: "{{ todo_response['returncode'] == 0 }}"
then:
- action: notify.mobile_app_iphone
data:
title: "ToDo"
message: "{{ todo_response['stdout'] }}"
else:
- action: notify.mobile_app_iphone
data:
title: "ToDo file error"
message: "{{ todo_response['stderr'] }}"
shell_command:
get_file_contents: "cat {{ filename }}"