Manage Blueprints

Manage Home Assistant blueprints — list, read, import, save, delete, or render a standalone config.

One interface for the whole blueprint lifecycle in the automation and script domains.

DO NOT use this to create an automation or script FROM a blueprint — that is ha_config_set_automation / ha_config_set_script with a use_blueprint config.

Use action="list" to discover installed blueprints, action="get" for one blueprint's metadata, inputs and YAML, action="import" to install one from a URL, action="save" to write YAML text to a blueprint path, action="delete" to remove an installed one, and action="substitute" to render a blueprint plus inputs into a standalone config (the UI's "Take control"). To duplicate a blueprint, get it and save its yaml under a new path; to edit one in place, get it, change the text, and save it back to the same path with overwrite=True.

get also reports used_by: the automations or scripts built on the blueprint, which is the UI's "Show automations using this blueprint". Check it before deleting — Home Assistant refuses to delete a blueprint anything still uses, and it goes on counting a consumer that has since taken control of its own config until that consumer is removed.

CAVEATS: get returns the on-disk YAML only when something can read it — an in-process server, the ha_mcp_tools component, the File & YAML Tools entry, or the blueprint's source_url; yaml_source names which one answered, and source_url text is a fresh download that can differ from the installed file. Core's blueprint API alone exposes metadata only, so a locally authored blueprint on a bare install has no readable text. save needs overwrite=True to replace an existing path and reloads every automation/script using it. delete requires confirm=True, and Home Assistant refuses it while any automation or script still uses the blueprint — the error lists the consumers. Both writes are snapshotted first when a copy can be read, so ha_manage_backup(scope="edits") can restore the previous file. substitute only renders — it writes nothing, so pass the returned config to ha_config_set_automation / ha_config_set_script to persist it. To convert an automation or script that ALREADY exists, prefer ha_config_set_automation / ha_config_set_script with take_control_of_blueprint=True: it renders with that item's own current inputs and saves the result over itself in one call, where substitute would need those inputs restated and the config written back by hand. Taking control does NOT free the blueprint — Home Assistant goes on counting a converted automation or script as a user of it, so delete stays refused until the consumers are removed.

EXAMPLES:

• List: ha_manage_blueprints(action="list", domain="automation")

• Get one (with its consumers in used_by): ha_manage_blueprints(action="get", path="homeassistant/motion_light.yaml")

• Import: ha_manage_blueprints(action="import", url="https://example.com/bp.yaml")

• Duplicate: ha_manage_blueprints(action="save", path="user/my_copy.yaml", yaml=)

• Edit in place: ha_manage_blueprints(action="save", path="user/motion.yaml", yaml=, overwrite=True)

• Delete: ha_manage_blueprints(action="delete", path="user/motion.yaml", confirm=True)

• Detach: ha_manage_blueprints(action="substitute", path="user/motion.yaml", input={"motion_sensor": "binary_sensor.hall"})

• Convert an existing consumer to a standalone config: ha_config_set_automation(identifier="automation.hall", take_control_of_blueprint=True)

RELATED TOOLS: ha_config_set_automation / ha_config_set_script to build on a blueprint or persist a substituted config, ha_config_remove_automation / ha_config_remove_script to clear consumers blocking a delete, ha_search to find them, and ha_manage_backup(scope="edits") to restore a deleted blueprint.

blueprint blueprints import delete remove unused substitute take-control list ha_get_blueprint ha_import_blueprint