Script syntax - Home Assistant 2026.8.1 Getting started Documentation Installation Automations Dashboards Voice assistants Device organization Energy management Templating Configuration using the YAML file Our hardware Home Assistant Green Connect ZBT-2 Connect ZWA-2 Voice Preview Edition Integrations Blog Need help? On this page Script syntax Perform an action Activate a scene Variables Scope of variables Test a condition Wait for time to pass (delay) Wait Wait for a template Wait for a trigger Wait timeout Wait variable Fire an event Raise and consume custom events Repeat a group of actions Counted repeat For each While loop Repeat until Repeat loop variable If-then Choose a group of actions Grouping actions Parallelizing actions Stopping a script sequence Continuing on error Disabling an action Respond to a conversation Home ▸ Documentation Script syntax A script is a sequence of steps that Home Assistant runs from top to bottom whenever you call it. Think of it as a small recipe: “turn on the porch light, wait 30 seconds, then send me a notification”. Once you have written a script, you can run it from a button on your dashboard, from Assist, from inside an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more], or from anywhere else that calls actions. Scripts and automations are very closely related. The only real difference is that an automation runs by itself when something triggers it, and a script runs when you call it. When the script runs as part of an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more], the trigger variable is also available. See Available-Trigger-Data. Script syntax The script syntax basic structure is a list of key/value maps that contain actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more]. If a script contains only 1 actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more], the wrapping list can be omitted. All actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] support an optional alias. # Example script integration containing script syntax script: example_script: sequence: # This is written using the Script Syntax - alias: "Turn on ceiling light" action: light.turn_on target: entity_id: light.ceiling - alias: "Notify that ceiling light is turned on" action: notify.notify data: message: "Turned on the ceiling light!" Script syntax Perform an action Activate a scene Variables Scope of variables Test a condition Wait for time to pass (delay) Wait Wait for a template Wait for a trigger Wait timeout Wait variable Fire an event Raise and consume custom events Repeat a group of actions Counted repeat For each While loop Repeat until Repeat loop variable If-then Choose a group of actions Grouping actions Parallelizing actions Stopping a script sequence Continuing on error Disabling an action Respond to a conversation Perform an action Performing an action can be done in various ways. For all the different possibilities, have a look at the actions page. - alias: "Bedroom lights on" action: light.turn_on target: entity_id: light.bedroom data: brightness: 100 Activate a scene Scripts may also use a shortcut syntax for activating scenesScenes capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red. [Learn more] instead of calling the scene.turn_on action. - scene: scene.morning_living_room Variables The variables actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] allows you to set/override variables that will be accessible by templates in actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] after it. See also script variables for how to define variables accessible in the entire script. - alias: "Set variables" variables: entities: - light.kitchen - light.living_room brightness: 100 - alias: "Control lights" action: light.turn_on target: entity_id: "{{ entities }}" data: brightness: "{{ brightness }}" Variables can be templated. - alias: "Set a templated variable" variables: blind_state_message: "The blind is {{ states('cover.blind') }}." - alias: "Notify about the state of the blind" action: notify.send_message target: entity_id: notify.my_device data: message: "{{ blind_state_message }}" Scope of variables The variables actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] assigns the values to previously defined variables with the same name. If a variable was not previously defined, it is assigned in the top-level (script run) scope. sequence: # Set the people variable to a default value - variables: people: 0 # Try to increment people if Paulus is home - if: - condition: state entity_id: device_tracker.paulus state: "home" then: - variables: people: "{{ people + 1 }}" paulus_home: true - action: notify.notify data: message: "There are {{ people }} people home" # "There are 1 people home" # Variable value is now updated - action: notify.notify data: message: "There are {{ people }} people home {% if paulus_home is defined %}(including Paulus){% endif %}" # "There are 1 people home (including Paulus)" Test a condition While executing a script you can add a condition in the main sequence to stop further execution. When a condition does not return true, the script will stop executing. For documentation on the many different conditions refer to the conditions page. Note The condition actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] only stops executing the current sequence block. When it is used inside a repeat action, only the current iteration of the repeat loop will stop. When it is used inside a choose action, only the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] within that choose will stop. # If paulus is home, continue to execute the script below these lines - alias: "Check if Paulus is home" condition: state entity_id: device_tracker.paulus state: "home" condition can also be a list of conditions and execution will then only continue if ALL conditions return true. - alias: "Check if Paulus ishome AND temperature is below 20" condition: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: numeric_state entity_id: "sensor.temperature" below: 20 Wait for time to pass (delay) Delays are useful for temporarily suspending your script and start it at a later moment. We support different syntaxes for a delay as shown below. # Seconds # Waits 5 seconds - alias: "Wait 5s" delay: 5 # HH:MM # Waits 1 hour - delay: "01:00" # HH:MM:SS # Waits 1.5 minutes - delay: "00:01:30" # Supports milliseconds, seconds, minutes, hours, days # Can be used in combination, at least one required # When using milliseconds, consider that delay as *at least* X milliseconds. It won´t be exact. # Waits 1 minute - delay: minutes: 1 All forms accept templates. # Waits however many minutes input_number.minute_delay is set to - delay: "{{ states('input_number.minute_delay') | multiply(60) | int }}" Wait These actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] allow a script to wait for entities in the system to be in a certain state as specified by a template, or some event to happen as expressed by one or more triggers. Wait for a template This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] evaluates the template, and if true, the script will continue. If not, then it will wait until it is true. The template is re-evaluated whenever an entity ID that it references changes state. If you use non-deterministic functions like now() in the template it will not be continuously re-evaluated, but only when an entity ID that is referenced is changed. If you need to periodically re-evaluate the template, reference a sensor from the Time and Date integration that will update minutely or daily. # Wait until media player is stopped - alias: "Wait until media player is stopped" wait_template: "{{ is_state('media_player.floor', 'stop') }}" Wait for a trigger This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] can use the same triggers that are available in an automation’s trigger section. See Automation Trigger. The script will continue whenever any of the triggers fires. All previously defined trigger variables, variables and script variables are passed to the trigger. # Wait for a custom event or light to turn on and stay on for 10 sec - alias: "Wait for MY_EVENT or light on" wait_for_trigger: - trigger: event event_type: MY_EVENT id: my_trigger - trigger: state entity_id: light.LIGHT to: "on" for: 10 You can assign an id to each trigger, just like you would do in an automation’s trigger section, but you won’t find it inside the trigger condition, which only lists the main automation triggers. You can however find it in a template as wait.trigger.id: - if: - condition: template value_template: "{{ wait.trigger.id == 'my_trigger' }}" then: - action: light.turn_on target: entity_id: light.living_room_table Wait timeout With both types of waits it is possible to set a timeout after which the script will continue its execution if the condition/event is not satisfied. Timeout has the same syntax as delay, and like delay, also accepts templates. # Wait for sensor to change to 'on' up to 1 minute before continuing to execute. - wait_template: "{{ is_state('binary_sensor.entrance', 'on') }}" timeout: "00:01:00" You can also get the script to abort after the timeout by using optional continue_on_timeout: false. # Wait for IFTTT event or abort after specified timeout. - wait_for_trigger: - trigger: event event_type: ifttt_webhook_received event_data: action: connected_to_network timeout: minutes: "{{ timeout_minutes }}" continue_on_timeout: false Without continue_on_timeout: false the script will always continue since the default for continue_on_timeout is true. Wait variable After each time a wait completes, either because the condition was met, the event happened, or the timeout expired, the variable wait will be created/updated to indicate the result. Variable Description wait.completed true if the condition was met, false otherwise wait.remaining Timeout remaining, or none if a timeout was not spe…