Scripts

The Scripts integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you use scriptsA script is a saved list of steps that runs when you start it, for example, from a dashboard, with Assist, or from an automation. Unlike an automation, a script has no triggers, so it doesn’t start by itself. [Learn more] in Home Assistant. A script is a saved list of steps that Home Assistant runs when you start it, for example, from a dashboard, with Assist, or from an automation.

Each script is an entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more], for example, script.wake_up, and is also available as an action. The integration also provides actions that control scripts as a whole, for example, to start or stop them. They are listed under List of actions.

To create and run scripts, and to learn when to use them, refer to Scripts.

The script entity

Each script has an entity, for example, script.wake_up. Its state is on while the script is running, and off otherwise. You can use it like other entities:

• To react when a script starts or finishes, use a State changed trigger on the script entity.
• To check whether a script is running, use a State condition.

The entity has these attributes:

• last_triggered: When the script was last started.
• mode: The mode of the script.
• current: How many runs there are right now. In the Queued mode, this includes the runs that are waiting in the queue.
• max: How many runs there can be at the same time, including runs that are waiting. Only for the Queued and Parallel modes.
• last_action: The name of the step that started most recently. It’s only there while the script runs.

Scripts in YAML

Scripts that you create in the editor are stored in the scripts.yaml file. You can also write scripts in YAML yourself. Only the scripts in scripts.yaml can be edited in the editor. You can view scripts from other files, for example, directly in 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, in the editor, but you can’t change them there.

In YAML, each script has a key, such as message_temperature in the example below. The key is also the name of the script’s action, for example, script.message_temperature.

message_temperature:
  sequence:
    - action: notify.notify
      data:
        message: "Current temperature is {{ states('sensor.temperature') }}"

Example with fields, variables, and a mode

This script turns on the bedroom lights, waits for the number of minutes that the minutes field asks for, and then turns on the living room lights. If it’s started again while it’s waiting, it starts over.

• Script: Wake up
  • Field: Minutes, a number from 0 to 60, with the Default 5
  • Mode: Restart
• Action: Log activity, with the message “started”
• Action: Turn on light
  • Target: Bedroom light (light.bedroom)
• Action: Wait for time to pass (delay)
  • Duration: The value of the Minutes field
• Action: Turn on light
  • Target: The light in the turn_on_entity variable, here the living room light (light.living_room)

The duration and the target come from templates, and the turn_on_entity variable is set for the whole script. You can only set these parts in YAML.

wake_up:
  alias: "Wake up"
  icon: "mdi:party-popper"
  description: >
    Turns on the bedroom lights and then the living room lights after a delay
  variables:
    turn_on_entity: light.living_room
  fields:
    minutes:
      name: "Minutes"
      description: >
        The amount of time to wait before turning on the living room lights
      default: 5
      selector:
        number:
          min: 0
          max: 60
          step: 1
          unit_of_measurement: minutes
          mode: slider
  # If started again while it's still running, start over
  mode: restart
  sequence:
    - action: logbook.log
      data:
        name: "Wake up"
        message: "started"
        entity_id: script.wake_up
    - alias: "Bedroom lights on"
      action: light.turn_on
      target:
        entity_id: light.bedroom
      data:
        brightness: 100
    - delay:
        minutes: "{{ minutes | default(5) }}"
    - alias: "Living room lights on"
      action: light.turn_on
      target:
        entity_id: "{{ turn_on_entity }}"

Passing values to a script in YAML

In YAML, when you run the script itself, every value in the data of the action becomes a variable in the script, even if the script has no field for it:

triggers:
  - trigger: light.turned_on
    target:
      entity_id: light.bedroom
actions:
  - action: script.notify_pushover
    data:
      title: "State change"
      message: "The light is on!"

With Turn on script, put the values under variables:

triggers:
  - trigger: light.turned_on
    target:
      entity_id: light.bedroom
actions:
  - action: script.turn_on
    target:
      entity_id: script.notify_pushover
    data:
      variables:
        title: "State change"
        message: "The light is on!"

Waiting for a script to finish in YAML

To do other steps while a script runs, and still wait for it later, start it with Turn on script, and wait until its entity is off again. This way, the first script also isn’t stopped if the second one fails:

script_1:
  sequence:
    - action: script.turn_on
      target:
        entity_id: script.script_2
    # Perform some other steps here while the second script runs
    # Now wait for the second script to finish
    - wait_template: "{{ is_state('script.script_2', 'off') }}"
    # Now do some other things
script_2:
  sequence:
    # Do some things at the same time as the first script
    - delay: 5

List of actions

The Scripts integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

• Reload scripts (script.reload) Reloads all the available scripts.

• Toggle script (script.toggle) Starts a script if it isn’t running, and stops it otherwise.

• Turn off script (script.turn_off) Stops a running script.

• Turn on script (script.turn_on) Runs the sequence of actions defined in a script.

For an overview of every action across all integrations, see the actions reference.

Examples of starting and stopping scripts

Scripts work well together with automations. An automation can start a script when something happens, give the script’s fields a value, or stop a script that is still running. These examples are automations that use the Wake up script from the example with fields, variables, and a mode.

Automation: run the wake-up script every morning

Every morning at 7:00, this automation runs the Wake up script, and fills in its Minutes field. Because the automation runs the script itself, the field appears as an input in the action.

• Trigger: Time, at 07:00
• Action: Wake up (the script)
  • Minutes: 10

alias: "Run the wake-up script every morning"
triggers:
  - trigger: time
    at: "07:00:00"
actions:
  - action: script.wake_up
    data:
      minutes: 10

Automation: stop the wake-up script when you turn off the bedroom light

If you turn off the bedroom light while the Wake up script is still waiting, this automation stops the script, so the living room lights don’t turn on.

• Trigger: Light turned off
  • Target: Bedroom light (light.bedroom)
• Condition: State
  • Entity: Wake up (script.wake_up)
  • State: On
• Action: Turn off script
  • Target: Wake up (script.wake_up)

alias: "Stop the wake-up script when the bedroom light turns off"
triggers:
  - trigger: light.turned_off
    target:
      entity_id: light.bedroom
conditions:
  - condition: state
    entity_id: script.wake_up
    state: "on"
actions:
  - action: script.turn_off
    target:
      entity_id: script.wake_up

Troubleshooting