Blueprints

A blueprint in Home Assistant is a reusable automation or script, most often shared and created by the community, that can be imported into your Home Assistant instance.

They are a great way to learn how to automate your home and an inspiration for new automation ideas, or just an easy way to get started. Blueprints are a great method to share your automation creations with others, so that others can apply them to their own homes.

Devices & entities¶

Spook adds one update entity for every automation or script blueprint you imported from a URL. No device: a blueprint is a file, and the updates page reads a row by the device it belongs to, so putting them all on one would leave every row saying the same thing.

Updates¶

Default entity ID: update.<blueprint name>

When you import a blueprint, Home Assistant writes down where it came from. Nothing ever looks at that address again. The blueprint’s author can fix a bug in it a week later and you would have no way of knowing, short of opening the forum topic and reading the YAML yourself.

Spook gives every one of those blueprints an update entity. It follows the address the blueprint came in with, roughly once a day, and tells you when what is there no longer matches what you have. Roughly, because each round picks its own moment for the next one somewhere in the following few hours: a fixed hour would have every installation that restarted after the same release knocking on the community forum together, every day, for ever. Pressing install fetches it again and writes it over the copy you have, exactly as Home Assistant’s own re-import button does, and reloads every automation and script using it.

The dialog offers to keep a copy of the file first, and it is worth ticking. Installing writes over the blueprint you have, and if you ever edited that blueprint yourself, your edits are what gets written over.

Only blueprints that came from a URL get one. A blueprint you wrote yourself has no source to check against, and the three example blueprints Home Assistant lays down for you are left alone as well: they point at Home Assistant’s development branch, which is not the version you are running.

Only automation and script blueprints, too. Those are the only two kinds whose users Home Assistant can list, and without that list there is no way to tell whether an update would leave one of them unable to load. An install button that cannot promise that is worse than no button at all, so template blueprints are left out until there is a way to check them.

Delete a blueprint, or take the source address back out of it, and the update entity goes with it. Blueprints raise no events, so nothing notices at the moment it happens: the next round does. One deleted while Home Assistant was stopped is caught the next time Spook starts, so you are not left with an entity in the list and no blueprint behind it.

Where the copies go¶

Beside the blueprint itself, in the same folder, with the date and time it was put there added to the filename:

config/blueprints/automation/frenck/motion_light.yaml
config/blueprints/automation/frenck/motion_light.yaml.2026-08-31_204512.bak
config/blueprints/automation/frenck/motion_light.yaml.2026-08-24_091133.bak

So a copy sits next to the blueprint it belongs to, wherever in blueprints/ that blueprint lives. The time is your own rather than UTC, so it reads by the same clock you do. The newest three per blueprint are kept, and installing a fourth update lets go of the oldest.

To go back to one, rename it over the blueprint it is a copy of and reload your automations or scripts. Nothing about a .bak file is special to Home Assistant, so whatever you already use to reach your configuration folder will do: the File editor or Studio Code Server add-ons, Samba, SSH. There is no action for it, because putting one back is a rename and the file is already sitting there.

The extension deliberately does not end in .yaml. Home Assistant reads every .yaml file under the blueprint folders as a blueprint, so a copy named that way would turn up in your blueprint list, and be given an update entity of its own.

What the update dialog tells you¶

Every other update dialog in Home Assistant shows you release notes. This one cannot, because there are none: a blueprint has no changelog, and the author is under no obligation to say anything anywhere.

So the dialog carries the next best thing. The address the blueprint came from, as a link, always, so you can go and read what actually changed before deciding. And a warning, because an update dialog looks the same whatever is behind it, and this one deserves a second thought: an author improving their blueprint and it still suiting the automations you built on it are two different things. Inputs get renamed. Behaviour gets rethought.

It also tells you what changed, which is Spook comparing the two files rather than the author saying anything:

**Compared with the copy you have:**
- **New settings**: Wait time
- What it does **changed**

What an author did, and what you get told:

Settings are named as their author named them, up to three of them. Past that you get the count, because eighty names is a wall rather than a release note, and they are all in the blueprint for whoever wants to read them.

The rename in that table is the one this exists for. An author who changes the key an input is stored under and leaves its label alone gives you two settings that read exactly the same, while whatever you filled in sits under the old key and the new version never looks there. So the key comes along whenever a label on its own would not tell them apart.

And if Spook cannot read the copy you have at that moment, it says so instead of saying nothing, because saying nothing reads as “nothing changed”.

Underneath that, what is built on the blueprint, because an update writes over a file other things are running on and which ones is not written down anywhere you can see:

**The following 2 automations are using this blueprint:**

- [Hallway light](/config/automation/edit/hallway)
- [Porch light](/config/automation/edit/porch)

Each one links to its editor, so you can go and look at what an update is about to reach before you install it. An automation written in YAML without an id: has no editor to open, so that one links to the overview page instead. And when nothing is built on it you get told that too, in as many words, because it means you can install without reading any further.

And underneath that, the difference itself, folded away because most people want the sentence above it:

@@ -7,11 +7,14 @@
       name: Motion sensor
     light_target:
       name: Light
+    wait_time:
+      name: Wait time
+      default: 120
 trigger:
 - platform: state
   entity_id: !input motion_entity
   to: 'on'
 action:
-- service: light.turn_on
+- service: light.toggle
   entity_id: !input light_target
 mode: restart

Both sides go through Home Assistant’s own YAML writer before being compared. Without that, the file on your disk (written by Home Assistant) and the one just fetched (in its author’s layout) differ in indentation and quoting before they differ in anything that matters: eleven lines of that on an eighteen-line blueprint that had not changed at all, and hundreds of those on a large one. What is left after writing both out the same way is only what moved. Past a hundred lines it stops and says how many more there were, because all of it travels to your browser whether you open it or not. And a blueprint past a few thousand lines is not compared line by line at all: the work grows with the square of the length, which on a real one of 36,000 lines came to ten seconds, all of it to build something that would then be cut to a hundred lines anyway.

What an update is going to cost you comes first, above everything else, because people do not read to the bottom for a headline. What changed and what is built on the blueprint are still there underneath, as context.

The colour is the whole of the message. Orange is your decision: what is listed will stop loading, and Spook is telling you so and installing it anyway if you say so. Red is Spook’s: it will not write this one at all.

There is exactly one red case. A blueprint that says it needs a newer Home Assistant than you are running cannot work on your installation no matter what you do to your automations, so writing it would break everything on it with no way out but upgrading Home Assistant.

Everything else is orange, including an update that adds a setting nobody has filled in yet. Those automations do stop loading, and that is worth saying loudly, but updating first and filling the new setting in afterwards is a perfectly ordinary way round and which way round you want is not Spook’s to decide. Nothing is lost either: a stopped automation keeps its configuration and its ID, its editor opens it as normal, and you fill in what the new version asks for. Ticking Create backup first means you can put the blueprint back as well.

Matter and ZHA put much the same warning in front of a firmware update, for much the same reason.

About those version numbers¶

They look like a1b2c3d4, and that is not Spook being clever. Blueprints have no version. There is nowhere in a blueprint to put one, because the format turns away anything it does not recognise, so no author can add one even if they wanted to.

So Spook uses a fingerprint of the contents instead. Same fingerprint, same blueprint. A different one means something in it changed. It cannot tell you whether that change is newer or better, only that it is not what you have.

The fingerprint is taken from what a blueprint says, not from how the file is laid out. Home Assistant does not keep the bytes it downloaded: it parses a blueprint and writes it back out in its own formatting, and that formatting is free to differ between installations and Home Assistant releases. Line width, quoting, whether an emoji is written out or escaped, all of it. None of that changes what the blueprint does, so none of it changes the fingerprint. Neither does the address it came from, which Home Assistant stores inside the blueprint on the way in, nor the order of the settings it fills in for a selector the author left blank: multiple, reorder and the like are Home Assistant’s doing, not the blueprint’s.

Comments and indentation are not part of it either, since neither survives being parsed. Reordering any other key is, though. Home Assistant renders some of them in the order they are written, a variables: block among them, so moving two keys around can change what a blueprint does. Spook keeps that order rather than trying to work out which mappings are the executable ones, because guessing wrong there would mean missing a real update rather than mentioning an extra one.

When an update would break your automations¶

An input without a default has to be filled in by whoever uses the blueprint. If a new version asks for one your automations do not set, every automation on that blueprint stops loading the moment the file is written, and the version they did work with is gone.

Spook checks before it writes anything, using Home Assistant’s own reckoning of what an input needs rather than a second opinion that could drift from it. If an update would leave your automations short it names them, and the settings each one is missing, above everything else in the dialog. It still installs if you ask it to: those automations stop loading, and they keep everything you set and their editors still open, so you fill the new setting in and they come back.

It checks the other way round too. A blueprint can be perfectly valid as a blueprint while what comes out of it is not something Home Assistant will take, because the blueprint format has nothing whatever to say about triggers, actions or a script’s sequence. So every automation and script on the blueprint is built against the new version and put through the same validation a reload would, and anything that would not load is named the same way. That one is for the blueprint’s author to fix rather than you: no setting you fill in will change it.

And where it cannot tell, it says so separately. Reading what an automation supplies to a blueprint relies on something Home Assistant does not offer publicly, and when that is out of reach Spook has nothing to go on. Those are listed as not known rather than as broken, because an automation nothing can be read about may be perfectly fine.

A blueprint that says it needs a newer Home Assistant than the one you are running is the one thing Spook refuses outright. Writing it would break every automation on it, on a version that was never going to work, and nothing you do to your own automations gets you out of that.

Actions¶

Spook adds the following new actions to your Home Assistant instance:

Import blueprint¶

Downloads and imports an automation/script blueprint, directly from the URL you pass into this action.

The url attribute is the URL to the blueprint you want to import. This can be any URL as long as it is a valid blueprint.

1
2
3
action: blueprint.import
data:
  url: "https://community.home-assistant.io/t/your-blueprint-url"

Repairs¶

Spook has no repair detections for this integration.

Use cases¶

Some use cases for the enhancements Spook provides for this integration:

• Automatically download and import Blueprints. For example, write a script that automatically downloads the top 10 Blueprints from the Home Assistant community forums.

• Get told when the author of a blueprint you use has changed it, instead of finding out months later that the bug you worked around was fixed all along.

• Put the blueprint update entities in an automation of your own, so a notification goes out when one of them has something new to say.

Blueprints & tutorials¶

There are currently no known blueprints or tutorials for the enhancements Spook provides for this integration. If you created one or stumbled upon one, please let us know in our discussion forums.

Feature requests, ideas, and support¶

If you have an idea on how to further enhance this integration, for example, by adding a new action, entity, or repairs detection; feel free to let us know in our discussion forums.

Are you stuck using these new features? Or maybe you’ve run into a bug? Please check the Support page on where to go for help.