In this guide I will explain what a Script is in Home Assistant (HA) in plain, everyday language, and walk you step by step through creating a practical Movie Mode script.
1. In plain language: what is a Script?
Think of Home Assistant as a smart butler.
- Device / Entity: the tools the butler holds, such as lights, a TV, or curtains.
- Automation: a standing order you give the butler, in the form if this, then that. For example: if you come home, turn on the light. It is triggered passively.
- Script: a combo move or a skill pack you teach the butler.
A simple analogy:A script is a macro, or a one-tap macro.
The biggest difference between a Script and an Automation:
- Automation: it acts on its own. It needs a trigger condition, such as a time of day or someone arriving.
- Script: it waits for your command. It stays idle until you, or an automation, call it once, then it runs through once.
2. A hand-holding tutorial for creating scripts in version 2025.12.2
Let us build a classic Movie Mode script.Goal: with one tap, the living room main light turns off, the light strip dims to 30 percent, and the TV turns on.
Step 1: Open the creation screen
- Open the Home Assistant web page or app.
- In the left sidebar, click Settings.
- Select Automations & Scenes.
- In the top tab bar, click Scripts.
- Click the Create Script button in the lower right corner.
- Select Create new script.
Step 2: Set the basic script information
In the editor at the top:
- Name: enter Movie Mode.
- Icon: you can pick a TV icon, such as mdi:movie-open.
- Mode: keep the default Single. This means that if the script is already running, tapping it again does nothing, which prevents conflicting duplicate runs.
Step 3: Add Actions (this is the core)
A script is simply a series of Actions. In version 2025.12 the interface is even more intuitive.
Action 1: Turn off the living room main light
- Click the Add Action button.
- In the search box, type turn off.
- Note: in HA 2025, Call Service has been renamed to Perform action, or you can simply select a device.
- The simplest way: click Device directly, then find your living room main light in the Device drop-down.
- In the Action area, select Turn off.
Action 2: Turn on the light strip and dim it (optional)
- Click Add Action again.
- This time let us search by action: type light.turn_on.
- Click Light: Turn on.
- Click Choose entity and check your living room light strip.
- Detailed parameters appear below. Check Brightness and drag the slider to 30 percent.
- Optional: check Color and choose a warm yellow or red.
Action 3: Turn on the TV
- Click Add Action again.
- Select Device and find your living room TV.
- For the action, select Turn on.
Step 4: Save and test
- Click the Save Script button in the lower right corner.
- After saving, click the three-dot icon in the upper right and select Run.
- Verify: did the lights turn off and the TV turn on? If so, congratulations, your script works.
3. How do you use this script?
Now that the script is built, how do you call it? There are usually two ways.
Option A: Put it on the dashboard and tap it manually
- Go back to your HA home page (Overview).
- Click the pencil icon in the upper right to edit the dashboard.
- Click Add Card in the lower right corner.
- Select the Button card.
- Under Entity, search for script.guan_ying_mo_shi, which is the script you just created, usually script. plus the pinyin of the name you gave it.
- Click Save. Now you have a switch on your dashboard. One tap puts the house into Movie Mode.
Option B: Pair it with an automation so it runs automaticallyYou can create an automation:
- Trigger: when the smart plug detects that the TV power draw is above 50W, which means the TV is on.
- Action: select Action, search for script.turn_on, and choose Movie Mode. This way, every time you turn the TV on with the remote, HA automatically adjusts the lights for you.
4. Advanced tips for version 2025.12 and later
- YAML syntax change: if you are an advanced user who likes reading code, note that in the 2025 versions the recommended YAML key for scripts is the plural form actions:. The old action: still works, but the new standard is plural.
- Wait: if your TV is slow to start, you can add a Wait for time to pass action of 5 seconds after the turn on TV action, then add a close the curtains action. This gives the script a better rhythm.
- LLM assistance: version 2025.12 integrates better with AI. You can expose this script to Assist, the voice assistant, then say to your phone: Hey, start Movie Mode, and it will run the script.
I hope this tutorial helps you master Home Assistant scripts easily. If you see errors, check whether the device entity names were selected correctly.
