Scripts

Understanding scripts in Home Assistant Core

Scripts are reusable sequences of actions that can be called from automations, scenes, or manually triggered. They provide a way to organize and reuse complex action sequences.

What is a Script?

A script is a named sequence of actions that can be executed on demand. Unlike automations, scripts don’t have triggers - they must be explicitly called via a service call.

Example Script

script:
  morning_routine:
    alias: "Morning Routine"
    description: "Turn on lights and start coffee maker"
    sequence:
      - service: light.turn_on
        target:
          entity_id: light.bedroom
        data:
          brightness: 128
      - delay: "00:00:30"
      - service: switch.turn_on
        target:
          entity_id: switch.coffee_maker

Script Structure

Scripts are entities with the domain script and are implemented in homeassistant/components/script/.

Script Entity

Each script is represented as an entity that extends ToggleEntity and RestoreEntity:

homeassistant/components/script/__init__.py:1-50

"""Support for scripts."""

from homeassistant.helpers.entity import ToggleEntity
from homeassistant.helpers.entity_component import EntityComponent
from homeassistant.helpers.restore_state import RestoreEntity

class BaseScriptEntity(ToggleEntity, RestoreEntity, ABC):
    """Base class for script entities."""

Key Properties

• entity_id: Format is script.<script_name>
• state: Either “on” (running) or “off” (not running)
• last_triggered: Timestamp of last execution
• mode: Execution mode (single, restart, queued, parallel)
• current: Number of currently running executions
• max: Maximum number of parallel/queued executions

Script Definition

Scripts are defined with the following structure:

script:
  script_name:
    alias: "Human-readable name"
    description: "What this script does"
    icon: "mdi:script"
    mode: single  # Execution mode
    max: 10  # Max parallel/queued runs
    fields:
      # Input parameters
      brightness:
        description: "Light brightness"
        example: 128
    variables:
      # Script variables
      delay_time: "00:00:30"
    sequence:
      # Actions to perform
      - service: light.turn_on
        data:
          brightness: "{{ brightness }}"

Execution Modes

Scripts support different execution modes when called while already running:

Mode	Behavior
single	Ignore new calls while running (default)
restart	Stop current run and start new one
queued	Queue new runs to execute sequentially
parallel	Run multiple instances in parallel

Mode Examples

script:
  single_mode:
    mode: single
    sequence:
      - delay: "00:01:00"
  
  restart_mode:
    mode: restart
    sequence:
      - delay: "00:01:00"
  
  queued_mode:
    mode: queued
    max: 5  # Maximum 5 queued runs
    sequence:
      - delay: "00:01:00"
  
  parallel_mode:
    mode: parallel
    max: 10  # Maximum 10 parallel runs
    sequence:
      - delay: "00:01:00"

Script Fields

Scripts can accept input parameters through fields:

script:
  set_light:
    fields:
      entity_id:
        description: "The light entity to control"
        example: "light.living_room"
        required: true
        selector:
          entity:
            domain: light
      brightness:
        description: "Brightness value"
        example: 128
        selector:
          number:
            min: 0
            max: 255
      color:
        description: "RGB color"
        example: "[255, 0, 0]"
    sequence:
      - service: light.turn_on
        target:
          entity_id: "{{ entity_id }}"
        data:
          brightness: "{{ brightness }}"
          rgb_color: "{{ color }}"

Variables

Scripts can define variables for use throughout the sequence:

script:
  notify_with_delay:
    variables:
      notification_delay: "00:00:05"
      notification_title: "Home Assistant"
    sequence:
      - delay: "{{ notification_delay }}"
      - service: notify.notify
        data:
          title: "{{ notification_title }}"
          message: "Script executed"

Calling Scripts

From YAML

# Call a script without parameters
service: script.morning_routine

# Call a script with parameters
service: script.set_light
data:
  entity_id: light.living_room
  brightness: 200
  color: [255, 0, 0]

# Turn on/off (same as calling)
service: script.turn_on
target:
  entity_id: script.morning_routine
data:
  variables:
    custom_var: value

From Python

Call Script

from homeassistant.components import script

# Check if script is running
is_running = script.is_on(hass, "script.morning_routine")

# Call script service
await hass.services.async_call(
    "script",
    "morning_routine",
    {},
    blocking=True,
)

# Turn on script with variables
await hass.services.async_call(
    "script",
    "turn_on",
    {
        "entity_id": "script.set_light",
        "variables": {
            "brightness": 200,
        },
    },
)

Script Actions

Scripts support all the same actions as automations:

Service Calls

sequence:
  - service: light.turn_on
    target:
      entity_id: light.living_room
    data:
      brightness: 255

Delays

sequence:
  - delay: "00:00:30"  # Fixed delay
  - delay:
      seconds: "{{ delay_seconds }}"  # Template delay

Waits

sequence:
  # Wait for condition
  - wait_template: "{{ is_state('binary_sensor.motion', 'off') }}"
    timeout: "00:05:00"
  
  # Wait for trigger
  - wait_for_trigger:
      - platform: state
        entity_id: binary_sensor.motion
        to: "off"
    timeout: "00:05:00"

Conditional Execution

sequence:
  - choose:
      - conditions:
          - condition: state
            entity_id: sun.sun
            state: "below_horizon"
        sequence:
          - service: light.turn_on
            data:
              brightness: 255
      - conditions:
          - condition: state
            entity_id: sun.sun
            state: "above_horizon"
        sequence:
          - service: light.turn_on
            data:
              brightness: 128
    default:
      - service: light.turn_off

Repeat Actions

sequence:
  # Repeat count
  - repeat:
      count: 3
      sequence:
        - service: light.toggle
          target:
            entity_id: light.living_room
        - delay: "00:00:01"
  
  # Repeat while
  - repeat:
      while:
        - condition: state
          entity_id: binary_sensor.motion
          state: "on"
      sequence:
        - service: light.turn_on
        - delay: "00:01:00"
  
  # Repeat until
  - repeat:
      until:
        - condition: state
          entity_id: binary_sensor.motion
          state: "off"
      sequence:
        - delay: "00:00:10"

Script Management

Services

# Turn on (run) script
service: script.turn_on
target:
  entity_id: script.morning_routine

# Turn off (stop) script
service: script.turn_off
target:
  entity_id: script.morning_routine

# Toggle script
service: script.toggle
target:
  entity_id: script.morning_routine

# Reload scripts
service: script.reload

Helper Functions

The script component provides helper functions:

homeassistant/components/script/__init__.py:130-187

@callback
def scripts_with_entity(hass: HomeAssistant, entity_id: str) -> list[str]:
    """Return all scripts that reference the entity."""
    return _scripts_with_x(hass, entity_id, "referenced_entities")

@callback
def scripts_with_device(hass: HomeAssistant, device_id: str) -> list[str]:
    """Return all scripts that reference the device."""
    return _scripts_with_x(hass, device_id, "referenced_devices")

@callback
def scripts_with_area(hass: HomeAssistant, area_id: str) -> list[str]:
    """Return all scripts that reference the area."""
    return _scripts_with_x(hass, area_id, "referenced_areas")

@callback
def scripts_with_blueprint(hass: HomeAssistant, blueprint_path: str) -> list[str]:
    """Return all scripts that reference the blueprint."""

Tracing

Scripts support execution tracing for debugging:

script:
  debug_example:
    trace:
      stored_traces: 10  # Number of traces to keep
    sequence:
      - service: light.turn_on
      - delay: "00:00:01"
      - service: light.turn_off

Traces provide:

• Execution timeline
• Variable values at each step
• Action results
• Execution duration

Blueprints

Scripts can use blueprints for reusability:

blueprint:
  name: Notification Script
  description: Send a notification with custom message
  domain: script
  input:
    notify_service:
      name: Notification Service
      selector:
        text:
    message:
      name: Message
      selector:
        text:

sequence:
  - service: "notify.{{ notify_service }}"
    data:
      message: "{{ message }}"

Response Data

Scripts can return response data:

script:
  calculate_value:
    sequence:
      - stop: ""
        response_variable: result
        data:
          value: "{{ 1 + 1 }}"

Call with response:

action:
  - service: script.calculate_value
    response_variable: my_result
  - service: notify.notify
    data:
      message: "Result: {{ my_result.value }}"

Best Practices

Descriptive Names

Use clear aliases and descriptions for better maintainability.

Parameterization

Use fields to make scripts reusable with different parameters.

Proper Mode

Choose execution modes that match your script’s behavior.

Error Handling

Use conditions and choose blocks to handle different scenarios.

Documentation

Include descriptions for fields to help users understand parameters.

Events

Script execution fires events:

EVENT_SCRIPT_STARTED = "script_started"

Event data includes:

• entity_id: The script entity
• name: Script name
• variables: Variables passed to script

Common Patterns

Notification Script

script:
  notify_all:
    fields:
      title:
        description: "Notification title"
      message:
        description: "Notification message"
    sequence:
      - service: notify.mobile_app
        data:
          title: "{{ title }}"
          message: "{{ message }}"
      - service: notify.tv
        data:
          message: "{{ title }}: {{ message }}"

Device Control

script:
  control_lights:
    fields:
      room:
        selector:
          entity:
            domain: light
      action:
        selector:
          select:
            options:
              - turn_on
              - turn_off
              - toggle
    sequence:
      - service: "light.{{ action }}"
        target:
          entity_id: "{{ room }}"

Related Resources

Automations

Learn how scripts integrate with automations

Scenes

Understand scene activation patterns

Service Calls

Explore the service call system

Templates

Master templating in scripts