In this article
A Home Assistant script can have several similar-looking identifiers: a display name, an entity ID, a direct-action key, and aliases for individual action steps. These values serve different purposes and do not always change together.
The most important documented distinction is this: if you change a script’s entity ID from script.wake_up to script.good_morning, its direct action remains script.wake_up. Home Assistant says the action keeps the key assigned when the script was first saved (script documentation).
Identifier map
| Value | Purpose | Result in the example |
|---|---|---|
| Display name | Human-readable name shown in the interface; Assist can run an exposed script by this name | May be changed to Good morning |
| Entity ID | Identifies the script entity in templates, YAML, and other automations | Changes to script.good_morning |
| Direct-action key | Invokes the script itself as an action | Remains script.wake_up |
| YAML top-level key | Defines the action name of a YAML-defined script | wake_up corresponds to script.wake_up |
| Action-step alias | Optional descriptive name for one step | Any label you assign |
| Storage location | Determines whether the script editor can modify the definition | The editor can modify scripts in scripts.yaml |
An entity ID and a direct-action key may initially have the same value, such as script.wake_up. After an entity-ID change, however, they can refer to different aspects of the script.
Display name: the human-readable label
When creating a script in the editor, you add its steps and give it a name. You can later change that name, along with the icon or description, without changing the script’s steps (script documentation).
For example:
Old name: Wake up
New name: Good morning
The display name also matters to Assist. Home Assistant documents that you can expose a script to Assist and ask Assist to run it by name (script documentation).
Renaming the script does not itself change its entity ID. Home Assistant presents these as separate operations: use Menu > Rename for the name and Menu > Settings for the entity ID. After renaming a script, you may choose to update its entity ID so that the two remain easy to associate (script documentation).
Entity ID: the script entity’s identifier
Every script is represented as an entity, such as script.wake_up (Scripts integration). Home Assistant describes the entity ID as the identifier that templates, YAML, and other automations use to refer to the script (script documentation).
You can change it by opening the script and selecting:
Menu > Settings > Entity ID
In Home Assistant’s documented example, the entity ID changes from:
script.wake_up
to:
script.good_morning
A generic script action can then target the renamed entity:
action: script.turn_on
target:
entity_id: script.good_morning
Here, script.turn_on is the action and script.good_morning is the entity it controls. Home Assistant documents script.turn_on as a way to start a script in the background and shows it targeting script entities (script documentation, Scripts integration).
Direct action: the original key remains
Home Assistant also makes each script available as its own action. Direct invocation in YAML looks like this:
action: script.wake_up
In the visual editor, you can select Add action and search for the script by name. This invokes the script itself (script documentation).
The documented rename example therefore produces this split:
- The script begins with the entity ID
script.wake_up. - Its entity ID changes to
script.good_morning. - Its direct action remains
script.wake_up.
These forms have different roles:
# Invoke the script directly with its retained action key
action: script.wake_up
# Start the renamed script entity with a generic action
action: script.turn_on
target:
entity_id: script.good_morning
Changing the entity ID does not change the script action’s name. The action retains the key the script had when it was first saved (script documentation).
Where the direct-action key comes from
For a YAML-defined script, the top-level key is also the name of its action (Scripts integration):
wake_up:
alias: "Wake up"
sequence:
- action: light.turn_on
target:
entity_id: light.bedroom
Each value has a separate job:
wake_upis the top-level script key."Wake up"is the script’s human-readable name.script.wake_upis the action name associated with the key.light.turn_onis an action inside the script’s sequence.
This relationship accounts for the documented result in which the action remains script.wake_up after the entity ID becomes script.good_morning. The cited documentation describes current behavior, but it does not provide a broader identifier-lifecycle or future compatibility guarantee.
Action-step aliases are descriptive labels
The word alias can also appear on an individual action step:
- alias: "Turn on the bedroom light"
action: light.turn_on
target:
entity_id: light.bedroom
An action-step name makes the step easier to find in a long automation and in its trace. YAML stores that name in alias (automation editor).
The alias and action fields have distinct roles: alias supplies the step’s optional name, while action identifies what the step executes (automation actions). An alias is therefore not the script entity ID or its direct-action key.
The editor’s storage boundary
The script editor can modify only scripts stored in scripts.yaml (Scripts integration). If a script is defined directly in another YAML file, such as configuration.yaml, Home Assistant documents a Menu > Migrate operation that saves the script in scripts.yaml. The documentation then separately instructs you to delete the old definition from its original YAML file (Scripts integration).
Storage location controls editor access; it is separate from the names used to identify or invoke the script.
The practical rule is simple: use the display name as the human-readable label, the entity ID when referring to the script entity, the retained action key for documented direct invocation, and an action-step alias to label an individual step. The cited pages do not establish automatic reference rewriting, dashboard behavior, rename effects in third-party integrations, or long-term compatibility guarantees.
No comments yet