Home Assistant Scripts: A Complete Guide

If you have spent any time building automations in Home Assistant, you will have noticed that certain action sequences crop up repeatedly — flash the hallway light when a delivery arrives, send a mobile notification with the current temperature, or run through a morning routine of adjusting heating and blinds. Copy-pasting the same block of YAML into every automation is both fragile and hard to maintain. Scripts solve this problem. They are named, reusable sequences of actions that you can call from automations, other scripts, your Lovelace dashboard, or even a voice command.

What Are Home Assistant Scripts?

A script is a saved sequence of actions with no built-in trigger. That is the key distinction from an automation: automations fire automatically in response to a trigger (a motion sensor tripping, the time reaching 07:00, a device coming online). Scripts simply sit there waiting to be called. This makes them ideal for shared logic that several automations need to invoke.

Compare the three tools side by side:

• Automations — trigger → optional condition → actions. Best for event-driven behaviour.
• Scripts — named action sequences called on demand. Best for reusable logic.
• Scenes — a snapshot of device states (lights at 30%, colour temperature 3000 K). No logic, just a fixed target state. Read the scenes guide for a full walkthrough.

A practical rule of thumb: if the same block of actions appears in more than one automation, extract it into a script. If you just want to restore a set of light or climate states, use a scene.

Creating a Script via the UI

The visual editor is the fastest way to get started. Navigate to Settings → Automations & Scenes → Scripts and click the blue Add Script button in the bottom-right corner. You can also go directly via my.home-assistant.io/redirect/scripts.

Home Assistant presents a blank script editor. Fill in:

1. Name — this becomes the entity ID (e.g. script.morning_routine). Choose something descriptive.
2. Icon — optional but helpful on dashboards.
3. Mode — controls behaviour when the script is called while already running (covered below).
4. Sequence — add actions using the Add Action button. The UI supports all action types: calling a service, adding a delay, waiting for a trigger, using choose/if-then logic, and more.

Click Save Script when done. The script is immediately available as script.your_script_name throughout Home Assistant.

Script YAML Structure

Every script follows the same YAML skeleton. If you prefer editing configuration files directly, scripts live in configuration.yaml under the script: key, or in a dedicated scripts.yaml file if you use the script: !include scripts.yaml split. Each script has a unique ID, an alias (human-readable name), a mode, and a sequence of actions.

script:
  morning_routine:
    alias: "Morning Routine"
    mode: single
    sequence:
      - action: light.turn_on
        target:
          entity_id: light.bedroom_ceiling
        data:
          brightness_pct: 60
          kelvin: 3500
      - delay:
          minutes: 5
      - action: climate.set_temperature
        target:
          entity_id: climate.hallway
        data:
          temperature: 20

This script turns on the bedroom ceiling light at 60% brightness and warm white, waits five minutes, then nudges the hallway thermostat to 20 °C — a sensible starting point for a UK winter morning.

Key Action Types

Scripts support the full Home Assistant Script Syntax. The most commonly used action types are:

• action (formerly service) — calls any Home Assistant service, such as light.turn_on, notify.mobile_app_iphone, or media_player.play_media.
• delay — pauses execution for a fixed duration (delay: "00:01:30" for 90 seconds, or delay: 5 for 5 seconds).
• wait_template — pauses until a Jinja2 template evaluates to true (e.g. wait until a media player stops).
• wait_for_trigger — pauses until one of the specified triggers fires, similar to automation triggers.
• choose — selects one branch of actions based on which conditions match first, equivalent to a switch/case statement.
• if / then / else — a simpler conditional for two-branch logic.
• repeat — loops a sequence a fixed number of times, over a list, while a condition holds, or until a condition becomes true.
• variables — sets local variables accessible by templates later in the sequence.
• stop — halts execution early, optionally flagging an error.
• parallel — runs multiple actions simultaneously rather than sequentially.

Script Modes Explained

The mode setting controls what happens when a script is called while a previous run is still in progress. Home Assistant offers four modes:

• single (default) — if the script is already running, the new call is ignored and a warning is logged. Use this for scripts where overlapping runs make no sense, such as a morning routine.
• restart — the running instance is stopped immediately and a fresh run starts. Useful for scripts that should always reflect the latest input, such as a dynamic notification that includes the current sensor value.
• queued — new calls wait in line; each run completes before the next starts. Set max to limit queue depth (default is 10). Good for scripts controlling physical devices in sequence.
• parallel — every call spawns an independent run simultaneously. Useful for sending notifications to multiple people at the same time.

script:
  send_alert:
    alias: "Send Alert Notification"
    mode: queued
    max: 5
    sequence:
      - action: notify.mobile_app_my_phone
        data:
          title: "Smart Home Alert"
          message: "{{ message }}"

Using Variables and Passing Data

Scripts become far more powerful when you pass data to them. There are two mechanisms: variables (defined inside the script for internal reuse) and fields (declared inputs that callers must or may provide).

Fields appear in the Home Assistant UI as labelled form fields when you add a script call action in an automation or dashboard. They also make scripts self-documenting:

script:
  notify_with_message:
    alias: "Send Custom Notification"
    mode: parallel
    fields:
      message:
        description: "The message body to send"
        example: "Motion detected in the garden"
        required: true
        selector:
          text:
      target_device:
        description: "Which phone to notify"
        example: "mobile_app_iphone"
        required: false
        default: "mobile_app_iphone"
    sequence:
      - action: notify.{{ target_device }}
        data:
          title: "Smart Home"
          message: "{{ message }}"

Calling this from an automation is then explicit and readable:

- action: script.notify_with_message
  data:
    message: "Front door opened while away"
    target_device: "mobile_app_my_iphone"

Calling Scripts from Automations and Dashboards

Scripts are called just like any other Home Assistant service. In an automation action, add an Action step and choose Script: Turn on (which fires-and-forgets) or Script: Run (script.NAME directly, which waits for completion).

From a Lovelace dashboard, add a Button card and set the tap action to Call service → script.turn_on with your script entity. This is an excellent way to add one-tap routines to a wall-mounted tablet.

From a voice assistant, simply say the script name if you have exposed it to Alexa or Google Assistant. Alternatively, create a short helper input_boolean and use it as a trigger in an automation that calls the script — a common pattern for voice-activated routines. If you are building more complex flows, you may prefer Node-RED, which provides a visual drag-and-drop alternative to YAML scripting.

Script Modes in YAML vs UI

Scripts created through the UI are stored in the .storage/ directory and are managed by Home Assistant automatically — you do not edit them directly. Scripts defined in configuration.yaml or scripts.yaml must be reloaded via Developer Tools → YAML → Reload Scripts (or a script.reload service call) after changes. The UI editor and YAML are interoperable: you can create a script in the UI and then click Edit as YAML within the editor to fine-tune it.

Best Practices for Naming and Organisation

Good naming saves hours of debugging later. Follow these conventions:

• Use a verb prefix: notify_, run_, set_, toggle_. For example: notify_all_phones, run_leaving_home_routine.
• Keep names lowercase with underscores — the entity ID inherits the alias.
• Group related scripts with a shared prefix (heating_, lighting_, security_) so they sort together in the UI.
• Add an icon to each script so it is recognisable on dashboards at a glance.
• Always set mode explicitly — relying on the single default can cause silent failures if a script is called in rapid succession.
• Keep scripts focused on one task. If a script is doing ten different things, split it into smaller scripts and call them in sequence.

5 Practical Script Ideas for UK Homes

Here are five ready-to-adapt scripts that solve common UK smart home scenarios.

1. Good Morning Routine

Gradually raise the bedroom lights to 80% over two minutes, set the heating to 20 °C, and send a mobile notification with the day's weather. Trigger it from an alarm automation or a bedside button.

2. Leaving Home Checklist

When you leave, the script turns off all lights, locks the smart lock, sets the heating to 15 °C eco mode, and arms the security system. A single dashboard button or NFC tag near the door fires it instantly — no need to check each device individually.

3. Boiler Boost Notification

Many UK homes have a manual boiler boost button on the thermostat. Replicate this in Home Assistant: the script turns on the hot water for 30 minutes (via a Tado or Hive integration), then sends a notification when the boost is complete. Pass a duration field so you can boost for 30, 45, or 60 minutes depending on the call.

4. Bedtime Wind-Down

Dim all living room lights to 10% over five minutes, turn off the TV, set the thermostat to 18 °C night mode, and lock the front door. Schedule it from an automation at 22:30 or add a voice command via Alexa.

5. Intruder Alert

If a door or window sensor triggers while the alarm is armed, flash all lights red at full brightness, activate any sirens, send a push notification with a camera snapshot, and log the event. Using mode: parallel ensures the lights, siren, and notification all fire simultaneously for maximum response speed.

Scripts vs Automations: When to Use Each

A useful mental model: automations are the when, scripts are the what. An automation listens for a trigger and then calls a script to do the work. This separation keeps your automations short and your logic centralised. When you need to change how the morning routine behaves, you edit one script rather than hunting through a dozen automations.

If you are new to Home Assistant's action syntax, the automations guide covers triggers and conditions in depth. For templating data inside scripts — pulling sensor values, formatting strings, doing maths — the template guide is the next step in levelling up your YAML skills.