home-assistant.io/source/_integrations/shell_command.markdown

title	description	ha_category	ha_iot_class	ha_release	ha_quality_scale	ha_codeowners	ha_domain
Shell Command	Instructions on how to integrate Shell commands into Home Assistant.	Automation	Local Push	0.7.6	internal	@home-assistant/core	shell_command

This integration can expose regular shell commands as services. Services 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.

Configuration

# Example configuration.yaml entry
# Exposes service shell_command.restart_pow
shell_command:
  restart_pow: touch ~/.pow/restart.txt

{% configuration %} alias: description: Give the shell command a name (alias) as a variable and set the command you want to execute after the colon. e.g., alias:the shell command you want to execute. required: true type: string {% endconfiguration %}

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 service data passed into the service call 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 system](https://github.com/home-assistant/operating-system), the commands are executed in the `homeassistant` 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.

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 after a timeout of 60 seconds, the result is only logged to Home Assistant log and the value of the sensor is not updated.

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.

{% raw %}

# Apply value of a GUI slider to the shell_command
automation:
  - alias: "run_set_ac"
    trigger:
      platform: state
      entity_id: input_number.ac_temperature
    action:
      service: 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'

{% endraw %}