ha-nexus-agent
ha-nexus-agent
Home Assistant 的 MCP 服务器 — 通过 21 个领域的 202 个工具让 AI 助手全面掌控您的智能家居:实体(支持批量控制 + 语音暴露)、自动化与脚本(完整 CRUD + 追踪)、蓝图、仪表盘、辅助功能、区域、设备注册表、日历、待办事项列表、历史记录、系统管理、YAML 配置文件、基于 Git 的版本控制、实时 WebSocket 事件、能源仪表盘偏好设置、区域(地理围栏)、标签与分类、模糊搜索与发现、通过 Supervisor 管理插件以及 HACS 集成。
适用于 Claude Code CLI、Claude Desktop、VS Code、Cursor、Windsurf、OpenAI Codex CLI、Gemini CLI。
安装 — Home Assistant 插件(推荐)
在 Home Assistant 中前往 设置 → 插件 → 插件商店
点击右上角三个点菜单 (⋮) → 仓库
添加:
https://github.com/Fistacho/ha-nexus-agent找到 Nexus Agent 并点击 安装
点击 启动
点击 打开 Web UI
Web UI 会显示您的 API 密钥,并为每个 MCP 客户端生成可直接粘贴的配置。无需手动设置令牌 — 插件会自动连接到 Home Assistant。
Related MCP server: ha-mcp
安装 — 独立运行(HA 外部)
git clone https://github.com/Fistacho/ha-nexus-agent
cd ha-nexus-agent
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set HA_URL and HA_TOKEN
python server.py打开 http://localhost:7123 以获取您的 API 密钥和 MCP 客户端配置。
获取 Home Assistant 令牌
在 HA 中前往 个人资料 → 安全 → 长期访问令牌
点击 创建令牌,命名为
nexus将其作为
HA_TOKEN粘贴到.env文件中
连接 MCP 客户端
启动 Nexus 后,打开 http://your-ha-ip:7123。设置页面会为每个客户端生成精确的命令或配置片段 — 只需复制并粘贴即可。
所有基于 SSE 的客户端连接地址为:
http://your-ha-ip:7123/mcp?token=YOUR_API_KEYClaude Code CLI
claude mcp add nexus --transport sse "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY" --scope userOpenAI Codex CLI
codex mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"Gemini CLI
gemini mcp add nexus --url "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"VS Code
创建 .vscode/mcp.json:
{
"servers": {
"nexus": {
"type": "sse",
"url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY"
}
}
}Cursor
粘贴到 ~/.cursor/mcp.json:
{
"mcpServers": {
"nexus": {
"url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
"type": "sse"
}
}
}Windsurf
粘贴到 ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"nexus": {
"url": "http://your-ha-ip:7123/mcp?token=YOUR_API_KEY",
"type": "sse"
}
}
}Claude Desktop(独立运行,子进程模式)
粘贴到 %APPDATA%/Claude/claude_desktop_config.json (Windows) 或 ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):
{
"mcpServers": {
"nexus": {
"command": "python",
"args": ["server.py"],
"cwd": "/path/to/ha-nexus-agent",
"env": {
"HA_URL": "http://homeassistant.local:8123",
"HA_TOKEN": "your_ha_token_here"
}
}
}
}提示: 从 Nexus Web UI (
http://your-ha-ip:7123) 复制确切的配置(包含您的真实路径和密钥)。
功能特性
202 个 MCP 工具,涵盖 21 个类别
实时 WebSocket — 实时订阅状态更改、事件和触发器
Git 版本控制 — 每次配置更改都会自动提交,支持即时回滚
YAML 验证 — 在写入任何配置文件前进行校验
设置 Web UI — 为每个客户端自动生成可直接使用的 MCP 配置
HA 插件原生支持 — 从插件商店一键安装,无需手动设置令牌
API 密钥认证 — MCP 端点受保护,令牌通过 URL 查询参数传递
工具概览
类别 | 数量 | 示例 |
| 17 | list_entities, turn_on/off/toggle, bulk_control, set/get_entity_exposure (语音助手) |
| 19 | call_service, send_notification, set_light_color, camera_snapshot, camera_record, persistent_notification 创建/关闭 |
| 21 | list/trigger/enable/disable, get/set/delete_automation_config (完整 YAML CRUD), list/get_automation_traces (调试),脚本和场景同理 |
| 4 | list, import (从 URL), delete, substitute (带输入参数实例化) |
| 8 | list_areas, create_area, get_area_states, control_area |
| 4 | list_devices, update_device (重命名/移动到区域/禁用), remove_device, list_devices_in_area |
| 4 | list_calendars, list_events, create_event, delete_event |
| 5 | list_todo_lists, list_items, add_item, update_item, remove_item |
| 11 | set_input_boolean, set_input_number, start_timer, increment_counter |
| 5 | get_state_history, get_logbook, get_error_log |
| 9 | check_config, create_backup, restart_ha, list_integrations |
| 6 | get_dashboard_config, add_card_to_view, add_view_to_dashboard |
| 6 | read_config_file, write_config_file, validate_yaml_content |
| 11 | git_commit_all, git_rollback_file, git_log, safe_write_with_checkpoint |
| 7 | listen_state_changes, listen_events, subscribe_trigger |
| 20 | 插件的 list/install/start/stop/restart/update/uninstall, addon_logs, addon_options, backups (列表/创建/恢复/删除), core/host 信息 + 重启 |
| 7 | HACS 仓库的 list/install/uninstall/update, 添加自定义仓库, 列出关键更新 |
Git 版本控制
Nexus 会保留您 HA 配置目录的 Git 历史记录。在进行任何高风险更改之前,请使用 git_safe_write_with_checkpoint — 它会先提交当前状态,然后再应用更改。如果出现问题,可以立即回滚。
git_init_config() # run once
git_safe_write_with_checkpoint("automations.yaml", new_content)
git_rollback_file("automations.yaml") # undo single file
git_rollback_to_commit("abc1234") # full rollback
git_log(limit=10) # see history环境变量
变量 | 必需 | 默认值 | 描述 |
| 是 |
| Home Assistant URL |
| 仅独立运行 | — | 长期访问令牌 |
| 仅插件 | 自动注入 | 由 HA 自动设置 |
| 用于 Git 工具 |
| HA 配置目录路径 |
| 否 | 自动生成 | 固定为特定的 API 密钥 |
| 否 |
| HTTP 服务器端口 |
Available Tools
349 toolsadguard_add_filterAdd AdGuard Home filter listAIdempotent
Add a filter list URL to AdGuard Home, waiting up to 180 s for AdGuard to download and parse it.
Reads filtering/status and, if the URL is not on either list yet,
sends POST /control/filtering/add_url {name, url, whitelist}; AdGuard
downloads and parses the list inside that request and enables it. Then
re-reads filtering/status.
Use when: adding a filter list, especially a large one — HA's
adguard.add_url service gives up after 10 s and then adds nothing.
Not for: refreshing lists — use the HA adguard.refresh service;
removing or toggling a list — use adguard_remove_filter or
adguard_set_filter_enabled.
Returns: {"added": true, "addon_slug", "list", "filter": {name, url, enabled, rules_count, last_updated}, "total_rules"}; total_rules sums
the enabled lists of the same kind.
Errors: invalid_name, invalid_url (no I/O), already_exists (with
list and filter, nothing sent), HTTP <status> with AdGuard's
detail, timeout, and the add-on lookup errors of adguard_get_config.
Limits: after a timeout AdGuard may still finish adding the list.
Inputs: url (required), name (required), allowlist. Returns: object
adguard_check_hostCheck a host against AdGuard filtersARead-onlyIdempotent
Check whether AdGuard Home would filter a domain, and by which rule and list.
Calls GET /control/filtering/check_host?name=<name> on the AdGuard Home
add-on and resolves each matched rule's filter_list_id to the list
name from filtering/status (0 = custom rules, negative ids = built-in
sources such as blocked services or safe browsing). Sends no DNS query
and changes nothing.
Use when: explaining why a domain is blocked or allowed.
Not for: the full filtering setup — use adguard_get_config.
Returns: AdGuard's answer (reason, rules, service_name, cname,
ip_addrs) plus name, blocked (true when reason starts with
Filtered) and filter_name on each rule.
Errors: invalid_name for an empty or malformed domain; the add-on
lookup errors of adguard_get_config.
Inputs: name (required). Returns: object
adguard_get_configGet AdGuard Home configurationARead-onlyIdempotent
Read the AdGuard Home add-on's status, DNS settings, filtering, safe search, access lists and dhcp state.
Finds the AdGuard Home add-on through the Supervisor, then reads its
local API (http://127.0.0.1:45158/control/...): status, dns_info
(upstreams, bootstrap, fallback, rate limit, cache, PTR), filtering/status
(lists with name/url/rules_count; custom rules as a count plus the first
20), safesearch/status, access/list and dhcp/status reduced to
enabled and interface_name (no leases). Changes nothing.
Use when: inspecting AdGuard before changing it, or answering what DNS
upstreams and filters are active.
Not for: changing DNS settings — use adguard_set_dns_config; testing one
domain against the filters — use adguard_check_host.
Returns: {"addon_slug", "status", "dns", "filtering", "safesearch", "access", "dhcp"}; a section AdGuard answers with an HTTP error holds
{"error": "HTTP <status>", "detail"} instead.
Errors: adguard_not_found, adguard_not_running,
adguard_unsupported_addon, adguard_unreachable, adguard_auth_required,
timeout, HTTP <status>, or a missing SUPERVISOR_TOKEN.
Inputs: no named parameters. Returns: object
adguard_remove_filterRemove AdGuard Home filter listADestructiveIdempotent
Remove one filter list from AdGuard Home by its exact URL.
Reads filtering/status; only when the URL is on the chosen list sends
POST /control/filtering/remove_url {url, whitelist} (AdGuard answers
OK even for an unknown URL, so the check runs first). AdGuard drops the
list from its config and renames the downloaded file to .old. Then
re-reads filtering/status.
Use when: dropping a blocklist or allowlist.
Not for: pausing a list you may want back — use
adguard_set_filter_enabled; adding one — use adguard_add_filter.
Returns: {"removed": true, "addon_slug", "list", "removed_filter", "filters": [{name, url, enabled, rules_count}], "total_rules"} for the
list kind after the change; total_rules sums its enabled lists.
Errors: invalid_url (no I/O), not_found (with found_in when the
URL is on the other list kind, nothing sent), HTTP <status> with
AdGuard's detail, and the add-on lookup errors of adguard_get_config.
Inputs: url (required), allowlist. Returns: object
adguard_set_dns_configSet AdGuard Home DNS settingsADestructive
Change selected AdGuard Home DNS settings after the new upstreams pass AdGuard's own test.
Reads dns_info, then — when upstream_dns, bootstrap_dns,
fallback_dns or local_ptr_upstreams change — runs
POST /control/test_upstream_dns on the resulting lists and writes
nothing unless every server answers OK. Then sends only the given
fields to POST /control/dns_config (AdGuard keeps the rest), and
re-reads dns_info. Applies immediately to the whole network.
Use when: changing upstream/fallback/bootstrap/PTR resolvers, rate
limit, cache, dnssec_enabled, blocking mode or upstream timeout.
Not for: reading the current values — use adguard_get_config; filter
lists — use adguard_add_filter, adguard_remove_filter or
adguard_set_filter_enabled.
Returns: {"applied": true, "addon_slug", "changed_fields", "before", "after", "upstream_test"}; before/after list the allowlisted fields.
Errors: invalid_changes, no_changes, upstream_test_failed (with
failed, nothing written), HTTP <status> with AdGuard's detail, and
the add-on lookup errors of adguard_get_config.
Limits: a domain-specific upstream reported as a WARNING also blocks the write.
Inputs: changes (required). Returns: object
adguard_set_filter_enabledEnable or disable AdGuard Home filter listAIdempotent
Turn one AdGuard Home filter list on or off, keeping its name and URL.
Reads filtering/status; if the list is already in the requested state
nothing is sent. Otherwise sends POST /control/filtering/set_url
{url, whitelist, data: {name, url, enabled}} with the list's current
name and URL, so only enabled changes; enabling makes AdGuard download
and parse the list inside the request. Then re-reads filtering/status.
Use when: pausing or resuming a list without losing its entry.
Not for: deleting a list — use adguard_remove_filter; adding one — use
adguard_add_filter; refreshing lists — use the HA adguard.refresh
service.
Returns: {"changed", "addon_slug", "list", "filter": {name, url, enabled, rules_count, last_updated}, "total_rules"}; total_rules sums
the enabled lists of the same kind.
Errors: invalid_url (no I/O), not_found (nothing sent), HTTP <status> with AdGuard's detail, timeout, and the add-on lookup
errors of adguard_get_config.
Limits: enabling waits up to 180 s; after a timeout AdGuard may still
finish the change.
Inputs: url (required), enabled (required), allowlist. Returns: object
areas_control_areaControl area entities by domainA
Turn on, off or toggle every entity of one domain in an area.
Calls service <domain>.<action> over HTTP with {"area_id": area_id}
as the target, so Home Assistant dispatches it to every entity of that
domain in the area. action must be one of turn_on/turn_off/toggle
(ADR-0006 D6) — an unchecked value here could reach an arbitrary
<domain>.<action> service under cover of "controlling an area".
Use when: controlling a whole area by domain, e.g. all lights in a room.
Not for: controlling an explicit list of entity_ids across areas — use
entities_bulk_control.
Returns: list of state-change dicts as returned by the HA service call.
Errors: raises ValueError when action is not one of turn_on,
turn_off, toggle.
Limits: an invalid domain (no such domain, or the domain has no
matching service) fails with the underlying HTTP error from Home
Assistant.
Inputs: action (required), area_id (required), domain. Returns: result
areas_create_areaCreate areaA
Create a new Home Assistant area (room).
Calls WS config/area_registry/create with name; Home Assistant
assigns a new area_id and there is no way to request a specific one, so
calling this twice with the same name creates two distinct areas.
Use when: you need a new area to assign devices, entities or labels to.
Not for: renaming an existing area or changing its icon, floor or
aliases — use areas_update_area.
Returns: the created area registry dict (area_id, name, floor_id, icon,
aliases, picture).
Inputs: name (required). Returns: object
areas_delete_areaDelete areaADestructiveIdempotent
Delete a Home Assistant area by its area_id.
Calls WS config/area_registry/delete; the area disappears from the
registry immediately. Home Assistant answers a plain "success", which
this tool reports as an object.
Use when: removing an area that is no longer used.
Returns: {"deleted": true, "area_id"}.
Limits: irreversible — there is no restore tool for a deleted area.
Inputs: area_id (required). Returns: object
areas_get_area_entitiesGet entities in areaARead-onlyIdempotent
Get every entity registered in a given area, directly or via its device.
Reads the entity and device registries over WebSocket, then keeps
entity-registry rows whose own area_id matches, or whose device_id
belongs to a device assigned to the area.
Use when: you need the entity registry rows for one area, e.g. before
bulk-editing labels or categories.
Not for: current state values — use areas_get_area_states, or a
combined view — use snapshot_get_area_snapshot.
Returns: list of entity registry dicts (entity_id, device_id, area_id,
labels, …) belonging to the area.
Limits: an unknown area_id returns an empty list rather than an error.
Inputs: area_id (required). Returns: result
areas_get_area_statesGet entity states in areaARead-onlyIdempotent
Get current states of every entity in a given area.
Calls areas_get_area_entities for the area, then filters the full
state list (ha.get_states()) down to the entity_ids found in that call.
Use when: you need live state values scoped to one area, e.g. before
deciding what to control.
Not for: registry rows without state values — use
areas_get_area_entities, or a combined view — use
snapshot_get_area_snapshot.
Returns: list of HA state objects (entity_id, state, attributes,
last_changed, last_updated) for entities in the area.
Inputs: area_id (required). Returns: result
areas_list_areasList areasARead-onlyIdempotent
List all Home Assistant areas (rooms).
Reads the area registry over WebSocket (config/area_registry/list) and
returns every entry exactly as Home Assistant reports it, unfiltered.
Use when: you need area IDs and names before assigning entities, devices or labels to an area. Returns: list of area registry dicts (area_id, name, floor_id, icon, aliases, picture).
Inputs: no named parameters. Returns: result
areas_list_devicesList all devices unfilteredARead-onlyIdempotent
List all devices in Home Assistant's device registry, unfiltered.
Calls WS config/device_registry/list via ha_client and returns every
registry entry exactly as Home Assistant reports it, with every field
(unlike the slimmed projection other tools apply).
Use when: you need the complete raw device registry, including fields
not exposed elsewhere.
Not for: a smaller per-field view — use devices_list_devices, which
projects each entry down to id/name/area_id/manufacturer/model/
entry_type plus config_entries/disabled_by; devices scoped to one area —
use devices_list_devices_in_area; fuzzy name-based search — use
search_search_devices.
Returns: list of full device registry dicts as returned by
config/device_registry/list.
Inputs: no named parameters. Returns: result
areas_list_floorsList floorsARead-onlyIdempotent
List all floors defined in Home Assistant.
Reads the floor registry over WebSocket (config/floor_registry/list)
and returns every entry exactly as Home Assistant reports it, unfiltered.
Use when: grouping areas by floor, e.g. before building a floor-scoped dashboard. Returns: list of floor registry dicts as reported by Home Assistant.
Inputs: no named parameters. Returns: result
areas_update_areaUpdate areaADestructiveIdempotent
Rename an area or change its icon, floor or aliases.
Calls WS config/area_registry/update; only the parameters you pass
are sent, so omitted fields keep their current value. The area_id
never changes, so entities and devices stay assigned to the area.
Use when: renaming a room, or moving it to another floor.
Not for: creating a new area — use areas_create_area; moving a
device or an entity between areas — use devices_update_device or
entities_assign_entity_to_area.
Returns: the updated area registry dict (area_id, name, floor_id, icon,
aliases, picture).
Errors: raises ValueError when no field to change is given; an
unknown area_id or floor_id, or a name already used by another area,
fails with the WS error from Home Assistant.
Limits: the previous values are not returned; aliases replaces the
whole list. The icon and floor cannot be cleared with this tool.
Inputs: area_id (required), icon, name, aliases, +1 more. Returns: object
automations_activate_sceneActivate a sceneAIdempotent
Activate a scene, applying its stored entity states.
Calls the scene.turn_on service with entity_id.
Returns: list[dict], the raw scene.turn_on service-call response.
Inputs: entity_id (required). Returns: result
automations_delete_automationDelete an automation configADestructiveIdempotent
Delete an automation by config id, then reload automations.
Without confirm=True returns a safety prompt; with confirm=True
deletes /api/config/automation/config/<id> and calls the
automation.reload service.
Returns: dict {"status": "deleted", "automation_id", "result"}.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is not True, or {"error": "not found", "automation_id": aid} when no automation has that config id.
Limits: requires confirm=True; deletion is immediate and permanent.
Inputs: automation_id (required), confirm. Returns: object
automations_delete_sceneDelete a scene configADestructiveIdempotent
Delete a scene config, then reload scenes.
Without confirm=True returns a safety prompt and touches nothing;
with confirm=True deletes /api/config/scene/config/<id> and calls
the scene.reload service.
Returns: dict {"deleted": sid, ...} merged with HA's delete response,
or {"status": "not_found", "scene_id": sid} when no scene has that
id.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is not True.
Limits: requires confirm=True; deletion is immediate and permanent.
Inputs: scene_id (required), confirm. Returns: object
automations_delete_scriptDelete a script configADestructiveIdempotent
Delete a script by id, then reload scripts.
Without confirm=True returns a safety prompt; with confirm=True
deletes /api/config/script/config/<id> and calls the script.reload
service.
Returns: dict {"status": "deleted", "script_id", "result"}.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is not True, or {"error": "not found", "script_id": sid} when no script has that id.
Limits: requires confirm=True; deletion is immediate and permanent.
Inputs: script_id (required), confirm. Returns: object
automations_disable_automationDisable an automationAIdempotent
Disable an automation so it stops reacting to its triggers.
Calls the automation.turn_off service with entity_id; the
automation's stored config is untouched, only its runtime state
changes.
Returns: list[dict], the raw automation.turn_off service-call
response.
Inputs: entity_id (required). Returns: result
automations_enable_automationEnable a disabled automationAIdempotent
Enable a disabled automation.
Calls the automation.turn_on service with entity_id.
Not for: running the automation's actions immediately — use
automations_trigger_automation.
Returns: list[dict], the raw automation.turn_on service-call response.
Inputs: entity_id (required). Returns: result
automations_get_automation_configGet an automation's stored configARead-onlyIdempotent
Get the stored config of one automation (automations.yaml) as a dict.
Requests /api/config/automation/config/<id> over HTTP and returns
the parsed JSON, or None on a 404 — including for automations defined
in packages/YAML without an id, since those have no config-id route.
Not for: the automation's current runtime state — use
automations_list_automations or entities_get_entity for that.
Returns: dict with id, alias, trigger/triggers,
condition/conditions, action/actions and mode, or None when
no automation has that config id.
Inputs: automation_id (required). Returns: result
automations_get_automation_traceGet one automation traceARead-onlyIdempotent
Get a full automation trace (steps, timing, condition results) for a specific run.
Calls the trace/get WebSocket command for domain 'automation',
automation_id and run_id.
Not for: finding which run_id to use — use
automations_list_automation_traces or
automations_get_last_automation_trace first.
Returns: dict with the full step-by-step trace for that run.
Limits: blocks for the WebSocket round trip.
Inputs: run_id (required), automation_id (required). Returns: object
automations_get_last_automation_traceGet the most recent automation traceARead-onlyIdempotent
Fetch the most recent trace for an automation in one call.
Calls trace/list for automation_id, then picks a run_id (the most
recent overall, or with failed_only=True the most recent whose
script_execution isn't 'finished') and calls trace/get for it.
Use when: debugging "why didn't this fire?" without first listing
traces and picking a run_id by hand.
Returns: dict with the full step-by-step trace for the picked run.
Errors: returns {"error": "no_traces"|"no_failed_traces", "automation_id": aid} when no matching run exists.
Limits: blocks for two sequential WebSocket round trips.
Inputs: automation_id (required), failed_only. Returns: object
automations_get_last_script_traceGet the most recent script traceARead-onlyIdempotent
Fetch the most recent (or most recent failed) trace for a script.
Calls trace/list for script_id, then picks a run_id (the most
recent overall, or with failed_only=True the most recent whose
script_execution isn't 'finished') and calls trace/get for it.
Use when: debugging why a script didn't behave as expected without
first listing traces and picking a run_id by hand.
Returns: dict with the full step-by-step trace for the picked run.
Errors: returns {"error": "no_traces"|"no_failed_traces", "script_id": sid} when no matching run exists.
Limits: blocks for two sequential WebSocket round trips.
Inputs: script_id (required), failed_only. Returns: object
automations_get_scene_configGet a scene's stored configARead-onlyIdempotent
Get a scene's stored config (member entities and their target states).
Requests /api/config/scene/config/<id> over HTTP and returns the
parsed JSON, or None on a 404.
Not for: the scene's current runtime state — use
automations_list_scenes or entities_get_entity for that.
Returns: dict with id, name and entities (mapping entity_id to
its target state dict), or None when no scene has that id.
Inputs: scene_id (required). Returns: result
automations_get_script_configGet a script's stored YAML configARead-onlyIdempotent
Get a script's stored YAML config as a dict.
Requests /api/config/script/config/<id> over HTTP and returns the
parsed JSON, or None on a 404.
Not for: the script's current runtime state — use
automations_list_scripts or entities_get_entity for that.
Returns: dict with the script's alias, sequence, fields and
mode, or None when no script has that id.
Inputs: script_id (required). Returns: result
automations_get_script_traceGet one script traceARead-onlyIdempotent
Get a full script trace (steps, timing, action results) for a specific run.
Calls the trace/get WebSocket command for domain 'script',
script_id and run_id.
Not for: finding which run_id to use — use
automations_list_script_traces or automations_get_last_script_trace
first.
Returns: dict with the full step-by-step trace for that run.
Limits: blocks for the WebSocket round trip.
Inputs: run_id (required), script_id (required). Returns: object
automations_list_automationsList automationsARead-onlyIdempotent
List all automations with their current state.
Reads ha.get_states() and keeps entries whose entity_id starts with
'automation.'.
Returns: list[dict] {"entity_id", "state", "friendly_name", "last_triggered"} per automation.
Inputs: no named parameters. Returns: result
automations_list_automation_tracesList automation trace summariesARead-onlyIdempotent
List trace summaries (recent runs) for an automation.
Calls the trace/list WebSocket command for domain 'automation' and
automation_id.
Returns: list[dict] of trace summaries (run_id, timestamps,
script_execution outcome) — no step-by-step detail; use
automations_get_automation_trace for one run's full detail.
Limits: blocks for the WebSocket round trip.
Inputs: automation_id (required). Returns: result
automations_list_groupsList entity groupsARead-onlyIdempotent
List all Home Assistant entity groups (group.* entities).
Reads ha.get_states() and keeps entries whose entity_id starts with
'group.', with their members, icon and current state.
Returns: list[dict] {"entity_id", "state", "friendly_name", "entity_ids", "icon", "all", "order"} per group.
Inputs: no named parameters. Returns: result
automations_list_scenesList scenesARead-onlyIdempotent
List all scenes.
Reads ha.get_states() and keeps entries whose entity_id starts with
'scene.'.
Returns: list[dict] {"entity_id", "friendly_name"} per scene.
Inputs: no named parameters. Returns: result
automations_list_scriptsList scriptsARead-onlyIdempotent
List all scripts with their current state.
Reads ha.get_states() and keeps entries whose entity_id starts with
'script.'.
Returns: list[dict] {"entity_id", "state", "friendly_name", "last_triggered"} per script.
Inputs: no named parameters. Returns: result
automations_list_script_tracesList script trace summariesARead-onlyIdempotent
List trace summaries (recent runs) for a script.
Calls the trace/list WebSocket command for domain 'script' and
script_id.
Returns: list[dict] of trace summaries (run_id, timestamps,
script_execution outcome) — no step-by-step detail; use
automations_get_script_trace for one run's full detail.
Limits: blocks for the WebSocket round trip.
Inputs: script_id (required). Returns: result
automations_reload_automationsReload all automations from YAMLAIdempotent
Reload all automations from YAML.
Calls the automation.reload service, which re-reads
automations.yaml/packages and re-applies enabled/disabled state; any
automations created only via automations_set_automation_config since
the last reload are included too, since that tool writes through the
same config store.
Returns: list[dict], the raw automation.reload service-call
response.
Inputs: no named parameters. Returns: result
automations_reload_scenesReload scenes from YAMLAIdempotent
Reload scenes from YAML.
Calls the scene.reload service, which re-reads scenes.yaml and
re-registers scene entities from it; scenes saved via
automations_set_scene_config are included since that tool writes to
the same config store.
Returns: list[dict], the raw scene.reload service-call response.
Inputs: no named parameters. Returns: result
automations_reload_scriptsReload all scripts from YAMLAIdempotent
Reload all scripts from YAML.
Calls the script.reload service, which re-reads scripts.yaml/packages
and re-registers script entities.
Returns: list[dict], the raw script.reload service-call response.
Inputs: no named parameters. Returns: result
automations_remove_groupRemove a runtime entity groupADestructiveIdempotent
Remove a group created with automations_set_group.
Without confirm=True returns a safety prompt; with confirm=True
calls the group.remove service with object_id. Groups defined in
groups.yaml come back on the next restart or YAML reload — this only
removes the runtime entity.
Returns: dict {"status": "removed", "group_id": "group.<id>"}.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is not True.
Limits: requires confirm=True; has no effect on a group defined in
groups.yaml beyond the next reload/restart.
Inputs: group_id (required), confirm. Returns: object
automations_run_scriptStart a scriptA
Start a script and return immediately without waiting for it to finish.
Calls the script.turn_on service with entity_id and, when given,
variables as the script's fields; the call returns as soon as Home
Assistant accepts it and does not return the script's response
variables.
Not for: getting the script's result — this tool never returns it,
regardless of the script's own response_variable.
Returns: list[dict], the raw script.turn_on service-call response.
Inputs: entity_id (required), variables. Returns: result
automations_set_automation_configCreate or overwrite an automation configADestructiveIdempotent
Create or replace the automation whose config id is automation_id.
Posts config to /api/config/automation/config/<id>, replacing the
whole stored config at that id (or creating a new automation if the id
is unused), then calls the automation.reload service.
Not for: editing a single field without resending the rest of the
config — this tool always replaces the whole stored config.
Returns: dict {"status": "saved", "automation_id", "result"}.
Errors: returns {"error": "config must be a dict"} when config
isn't a dict, or {"error": "config must contain at least 'alias' or 'trigger'/'triggers'"} when both are missing.
Limits: no confirm parameter; an existing automation at
automation_id is replaced without a prompt.
Inputs: config (required), automation_id (required). Returns: object
automations_set_groupCreate or update a runtime entity groupA
Create or update an old-style group.* entity at runtime.
Calls the group.set service with object_id=group_id and whichever
of name/entities/icon/all/add_entities/remove_entities were
given. The group is NOT written to groups.yaml and disappears on
restart or automations_reload_groups-style YAML reload; for a
persistent group use a Group helper or add it to groups.yaml with the
files_write_config_file tools. Does not create light/switch/cover
group helpers.
Not for: a group that survives a restart — define it in groups.yaml
instead (files_write_config_file) or create a Group helper.
Returns: dict {"status": "set", "group_id": "group.<id>"}.
Errors: returns {"error": "entities cannot be combined with add_entities/remove_entities — pass a full member list via entities, or incremental changes via add_entities/remove_entities, not both"} when
entities is given together with add_entities or remove_entities;
group.set is not called in that case.
Limits: entities replaces the whole member list and must not be
combined with add_entities/remove_entities in the same call.
Inputs: group_id (required), icon, name, entities, +3 more. Returns: object
automations_set_scene_configCreate or overwrite a scene configADestructiveIdempotent
Create or overwrite a scene's stored config, then reload scenes.
Posts {id, name, entities} to /api/config/scene/config/<id>,
replacing any existing config at that id, then calls the
scene.reload service so the change takes effect immediately.
Not for: applying the scene's states right now — use
automations_activate_scene.
Returns: dict {"scene_id", "name", "entity_count", ...} merged with
HA's save response.
Errors: returns {"error": "entities must be a non-empty dict of {entity_id: state_dict}"} when entities is empty or not a dict.
Limits: no confirm parameter; an existing scene at scene_id is
replaced without a prompt.
Inputs: name (required), entities (required), scene_id (required). Returns: object
automations_set_script_configCreate or overwrite a script configADestructiveIdempotent
Create or overwrite a script's stored YAML config, then reload scripts.
Posts config to /api/config/script/config/<id>, replacing the whole
stored config at that id (or creating a new script if the id is
unused), then calls the script.reload service.
Not for: running the script — use automations_run_script.
Returns: dict {"status": "saved", "script_id", "result"}.
Errors: returns {"error": "config must be a dict"} when config
isn't a dict, or {"error": "config must contain at least 'alias' or 'sequence'"} when both are missing.
Limits: no confirm parameter; an existing script at script_id is
replaced without a prompt.
Inputs: config (required), script_id (required). Returns: object
automations_trigger_automationTrigger an automation nowA
Run an automation's actions now, skipping its normal trigger.
Calls the automation.trigger service with entity_id; Home Assistant
skips the automation's conditions by default (skip_condition=true),
so this can fire actions the automation's own conditions would
otherwise block.
Use when: testing or forcing an automation's actions on demand.
Returns: list[dict], the raw automation.trigger service-call
response from Home Assistant.
Inputs: entity_id (required). Returns: result
automations_validate_automation_referencesCross-check automation YAML against live HAARead-onlyIdempotent
Cross-check entity IDs and services used in automation YAML against the live registry.
Unlike automations_validate_best_practices (static), this calls
ha.get_states() and ha.list_services() to verify that every literal
entity_id value and every literal service:/action: string in
yaml_content exists. It only looks at literal values — it does NOT
resolve device_id, area_id, label_id, or any templated reference,
not just the ones containing '{{ ... }}' (which are explicitly skipped
and counted in template_refs_skipped).
Use when: checking that an automation's references are real before
saving it with automations_set_automation_config.
Not for: YAML syntax or authoring-rule checks — use
automations_validate_best_practices.
Returns: dict {valid_yaml, automations_checked, entities_checked, services_checked, missing_entities[], missing_services[], template_refs_skipped, entities_check, services_check, errors[], summary}. entities_check/services_check are 'ok' or 'unavailable'.
Errors: returns {"valid_yaml": False, "error": "YAML parse error: ..."} for invalid YAML. When ha.get_states() or ha.list_services()
raises, the matching entities_check/services_check is 'unavailable'
and errors names which fetch failed; the corresponding missing_*
list stays empty rather than reporting a false "nothing missing" or a
false "everything is missing".
Limits: fetches the full live state list and full service list on
every call.
Inputs: yaml_content (required). Returns: object
automations_validate_best_practicesValidate automation YAML authoring rulesARead-onlyIdempotent
Validate automation YAML against static Home Assistant authoring rules.
Parses yaml_content with plain yaml.safe_load (HA-only tags like
!input/!secret are NOT resolved and make parsing fail with a YAML
parse error, same as any other unknown tag) and runs fixed checks: a
state trigger without 'for:', a missing 'mode:', multiple triggers
without 'id:', a missing 'alias:'/'id:', the deprecated 'service:'
action key, 'restart' mode, and a missing 'description:'.
Use when: linting automation YAML before saving it with
automations_set_automation_config.
Not for: checking that referenced entities/services actually exist —
use automations_validate_automation_references; blueprint content
with unresolved '!input'/'!secret' tags — extract them to plain YAML
first.
Returns: dict {valid_yaml, automations_checked, issues_total, warnings, infos, issues[], summary}; each issue is {automation, rule, severity, message} with severity 'warning' (should fix) or
'info' (good to know).
Errors: returns {"valid_yaml": False, "error": "YAML parse error: ...", "issues": []} for invalid YAML.
Inputs: yaml_content (required). Returns: object
blueprints_delete_blueprintDelete an installed blueprintADestructiveIdempotent
Delete an installed blueprint by its relative path.
Calls the blueprint/delete WebSocket command for domain/path; the
file under /config/blueprints// is removed and its content is
lost, with no backup taken by this tool.
Not for: automations or scripts generated from this blueprint — they
keep running with their already-substituted config; use
automations_delete_automation or automations_delete_script for
those.
Returns: {"deleted": true, "domain", "path"} (Home Assistant itself
answers with no payload).
Limits: blocks for the WebSocket round trip; the default 10 second
response wait in ha._ws_call applies. No confirm parameter guards
this deletion.
Inputs: path (required), domain. Returns: object
blueprints_import_blueprintImport and validate a blueprint from a URLARead-onlyIdempotent
Fetch a blueprint from a URL and validate it without saving it.
Calls the blueprint/import WebSocket command, which has Home Assistant
download url and validate its YAML. This only downloads and
validates — it does NOT save anything to disk.
Use when: previewing a blueprint (its metadata and validation errors)
before deciding to persist it.
Not for: persisting the fetched blueprint — pass its raw_data and
suggested_filename to blueprints_save_blueprint.
Returns: dict with suggested_filename, raw_data (the blueprint YAML
text), blueprint.metadata, validation_errors and exists (whether a
blueprint already sits at that path).
Limits: blocks for the WebSocket round trip plus the remote download
time; the default 10 second response wait in ha._ws_call applies.
Inputs: url (required), domain. Returns: object
blueprints_list_blueprintsList installed blueprintsARead-onlyIdempotent
List all installed blueprints for a domain over the WebSocket API.
Calls the blueprint/list WebSocket command via ha._ws_call for the
given domain and returns Home Assistant's response unchanged; nothing
is read from disk directly here.
Use when: enumerating what blueprints exist under
/config/blueprints/ before importing, substituting or deleting
one.
Returns: dict keyed by blueprint path, each value the blueprint's
metadata (name, description, domain, source_url) as returned by HA.
Limits: blocks for the WebSocket round trip; the default 10 second
response wait in ha._ws_call applies.
Inputs: domain. Returns: object
blueprints_save_blueprintSave a blueprint fileADestructiveIdempotent
Save blueprint YAML to /config/blueprints//.
Calls the blueprint/save WebSocket command with yaml_content as the
payload and overwrite mapped to HA's allow_override flag; with
overwrite=False (default) it does not replace an existing file at
path, and with overwrite=True it does, losing the previous content.
Not for: fetching a blueprint from the internet first — use
blueprints_import_blueprint to get raw_data/suggested_filename.
Returns: Home Assistant's blueprint/save result (typically an empty
success payload).
Errors: Home Assistant raises a WebSocket error, surfaced by
ha._ws_call as a RuntimeError, when overwrite=False and a file
already exists at path.
Limits: blocks for the WebSocket round trip; the default 10 second
response wait in ha._ws_call applies. No confirm parameter — the
only overwrite guard is the overwrite flag itself.
Inputs: path (required), yaml_content (required), domain, overwrite, +1 more. Returns: object
blueprints_substitute_blueprintRender a blueprint with given inputsARead-onlyIdempotent
Render a blueprint with given inputs into a plain automation or script.
Calls the blueprint/substitute WebSocket command, which resolves
input against the blueprint's input: placeholders and returns the
resulting config; nothing is saved or reloaded by this tool.
Use when: previewing the concrete triggers/conditions/actions a
blueprint would produce before saving it via
automations_set_automation_config or automations_set_script_config.
Returns: dict with the substituted automation/script YAML content as a
dict.
Limits: blocks for the WebSocket round trip; the default 10 second
response wait in ha._ws_call applies.
Inputs: path (required), input (required), domain. Returns: object
calendar_create_eventCreate a calendar eventA
Create a new event on a calendar via the calendar.create_event service.
Maps start/end to the service's start_date_time/end_date_time
fields. Calling this twice with identical arguments creates two
separate events, since HA assigns each a new uid.
Use when: adding a new event to a calendar that supports creation (local
or CalDAV calendars).
Not for: removing an event — use calendar_delete_event.
Returns: {"entity_id", "summary", "start", "end", "result": ...} where
result is the service-call response.
Inputs: end (required), start (required), summary (required), entity_id (required), +2 more. Returns: object
calendar_delete_eventDelete a calendar eventADestructiveIdempotent
Delete a calendar event by its uid via WS calendar/event/delete.
Only works for calendar platforms that declare
CalendarEntityFeature.DELETE_EVENT (e.g. local/CalDAV calendars);
read-only integrations such as Google Calendar reject it, and this
returns ok: False with HA's error instead of raising.
Use when: removing an event or a recurring instance from a calendar
that supports deletion.
Not for: creating an event — use calendar_create_event; not for
read-only calendar integrations, which will fail here regardless of
arguments.
Returns: {"entity_id", "uid", "result": ..., "ok": True} on success.
Errors: {"entity_id", "uid", "ok": False, "error": str(e)} when the
platform rejects the deletion or the WS call otherwise raises.
Inputs: uid (required), entity_id (required), recurrence_id, recurrence_range. Returns: object
calendar_list_calendarsList calendar entitiesARead-onlyIdempotent
List every calendar.* entity known to HA.
Calls GET /api/calendars over HTTP.
Use when: discovering which entity_id to pass to
calendar_list_events/calendar_create_event/calendar_delete_event.
Not for: the events within a calendar — use calendar_list_events.
Returns: list of {"entity_id", "name"} dicts, or an empty list if the
response isn't a JSON list.
Inputs: no named parameters. Returns: result
calendar_list_eventsList events on a calendarARead-onlyIdempotent
List events on one calendar between start and end.
Calls GET /api/calendars/{entity_id} over HTTP with start/end as
query parameters.
Use when: reading a calendar's upcoming or past events for a known date
range.
Not for: listing the calendar entities themselves — use
calendar_list_calendars.
Returns: list of event dicts as returned by HA (fields include summary,
start, end, uid), or an empty list if the response isn't a JSON
list.
Inputs: end (required), start (required), entity_id (required). Returns: result
card_builder_build_from_recipeBuild card config from recipeARead-onlyIdempotent
Materialise a recipe shorthand into a full DocumentData (config) dict.
Builds a canvas root wrapping one block-container, recursively
turns recipe["blocks"] into the block tree via _build_block_tree
(auto-inserting block-drop-zone children for layout blocks and
auto-wrapping raw prop scalars in {"value": ...}), and returns the
assembled {version, rootId, slots, blocks} dict. Pure computation —
makes no call to Home Assistant.
Use when: turning a recipe (hand-written or from
card_builder_get_card_template) into the config to pass to
card_builder_create_card/card_builder_update_card.
Not for: hand-crafted low-level DocumentData — assemble that directly
instead; a template-driven one-shot creation — use
card_builder_make_template_card.
Returns: a dict ready to pass as config to card_builder_create_card.
Errors: raises ValueError when recipe["root_slot"] isn't defined in
recipe["slots"], when a block in recipe["blocks"] has an unknown or
internal type, or when a non-container block type is given
children.
Limits: run card_builder_validate_config on the result before
saving — this tool does not validate the produced tree itself.
Inputs: recipe (required). Returns: object
card_builder_build_stylesCompose styles from snippetsARead-onlyIdempotent
Compose a styles object from one or more built-in snippets plus optional overrides.
Merges each named entry from STYLE_SNIPPETS in order, then extra,
at the property level — later entries override earlier ones for the
same category/property; makes no call to Home Assistant.
Use when: assembling a block's styles/dz_styles from reusable
presets instead of hand-writing the full envelope.
Returns: {<target>: {containers: {<container>: {<category>: {<prop>: <value>, ...}, ...}}}}.
Errors: {"error": "unknown_snippet", "name": ..., "known": [...]}
when a name in snippet_names isn't a known snippet.
Inputs: snippet_names (required), extra, target, container. Returns: object
card_builder_check_schema_syncCheck embedded schema against upstreamARead-onlyIdempotent
Compare the embedded block schema against upstream Card Builder's main branch on GitHub.
Fetches custom_components/card_builder/manifest.json and
frontend/src/common/blocks/loader.ts from
raw.githubusercontent.com/{UPSTREAM_REPO}/main over HTTP and diffs
the upstream version/block list against this module's BLOCK_TYPES
and UPSTREAM_SCHEMA_SYNC constants. Reaches outside the HA instance
and its host.
Use when: a recipe that used to work stops producing the expected
card — the upstream integration may have shipped a breaking schema
change.
Returns: {status: "ok"|"drift"|"fetch_failed", upstream_version, embedded_version, version_matches, missing_block_types, extra_embedded_block_types, advice, embedded_schema, ...}.
Errors: {"status": "fetch_failed", "error": <exception text>, "embedded": ...} when the manifest request itself fails (a timeout or
network error); a failed loader fetch instead sets loader_fetch_error
and still returns status.
Limits: two GitHub requests with a 10-second timeout each.
Inputs: no named parameters. Returns: object
card_builder_create_cardCreate Card Builder cardA
Create a new Card Builder card from a DocumentData config.
Sends config and the metadata fields to card_builder/cards/create,
which assigns a new id server-side (confirmed in upstream storage.py:
every create path generates a fresh uuid4) — repeating this call with
identical arguments creates a second, distinct card rather than
updating the first.
Use when: saving a card built with card_builder_build_from_recipe or
card_builder_make_template_card's underlying recipe.
Not for: changing an existing card — use card_builder_update_card.
Returns: the created card dict, including its new id.
Limits: run card_builder_validate_config on config first; this tool
does not validate the block tree before sending it.
Inputs: name (required), config (required), tags, author, +2 more. Returns: object
card_builder_create_css_custom_propertyCreate CSS custom propertyA
Register a new CSS custom property (@property) for use in card styles.
Sends the four fields to card_builder/css_custom_properties/create,
which assigns a new id server-side (confirmed in upstream
storage.py: every create path generates a fresh uuid4) — repeating
this call registers a second, distinct property rather than updating
the first.
Use when: defining an animatable/typed CSS variable (e.g. a themeable
accent color) that card styles can reference by name.
Returns: the created CSS-custom-property dict, including its new id.
Inputs: name (required), syntax (required), initial_value (required), inherits. Returns: object
card_builder_create_style_presetCreate Card Builder style presetA
Create a new reusable Card Builder style preset.
Sends data and the metadata fields to card_builder/style_presets/create,
which assigns a new id server-side (confirmed in upstream storage.py:
every create path generates a fresh uuid4) — repeating this call
creates a second, distinct preset rather than updating the first.
Use when: packaging a reusable set of style properties (e.g. a card
theme) to apply across multiple cards.
Not for: changing an existing preset — use
card_builder_update_style_preset.
Returns: the created style-preset dict, including its new id.
Inputs: data (required), name (required), description, extends_preset_id. Returns: object
card_builder_delete_cardDelete Card Builder cardADestructiveIdempotent
Permanently delete one Card Builder card by id.
Calls card_builder/cards/delete; Home Assistant's WebSocket handler
returns an empty payload on success. Any dashboard still referencing
this card_id via custom:card-builder-renderer-card will show a
broken/empty card afterwards — this tool does not check for or update
such references.
Use when: removing a card that is no longer used on any dashboard.
Returns: {"status": "deleted", "card_id": ..., "result": ...} on
success.
Errors: on failure, returns {"status": "error", "card_id": ..., "error": <exception text>} instead of raising.
Inputs: card_id (required). Returns: object
card_builder_delete_css_custom_propertyDelete CSS custom propertyADestructiveIdempotent
Permanently delete one registered CSS custom property by id.
Calls card_builder/css_custom_properties/delete. Any card style
still referencing this property's name keeps that reference — the
browser falls back to an unset CSS variable — this tool does not check
for or update such references.
Use when: removing a custom property that is no longer used by any
card style.
Returns: {"status": "deleted", "custom_property_id": ..., "result": ...} on success.
Errors: on failure, returns {"status": "error", "custom_property_id": ..., "error": <exception text>} instead of raising.
Inputs: custom_property_id (required). Returns: object
card_builder_delete_mediaDelete Card Builder media fileADestructiveIdempotent
Permanently delete one file from the Card Builder media directory.
Calls card_builder/media/delete with path relative to
www/card_builder/. Any card whose mediaReference points at this
file (e.g. via block-image or block-weather-background) will fail
to load it afterwards — this tool does not check for or update such
references.
Use when: removing an uploaded image/SVG that no card uses anymore.
Returns: {"status": "deleted", "path": ..., "result": ...} on
success.
Errors: on failure, returns {"status": "error", "path": ..., "error": <exception text>} instead of raising.
Inputs: path (required). Returns: object
card_builder_delete_style_presetDelete Card Builder style presetADestructiveIdempotent
Permanently delete one Card Builder style preset by id.
Calls card_builder/style_presets/delete. Any card whose style data
references this preset via extends_preset_id keeps that dangling id —
this tool does not check for or update such references.
Use when: removing a preset that is no longer extended by any card or
other preset.
Returns: {"status": "deleted", "style_preset_id": ..., "result": ...}
on success.
Errors: on failure, returns {"status": "error", "style_preset_id": ..., "error": <exception text>} instead of raising.
Inputs: style_preset_id (required). Returns: object
card_builder_design_for_intentRecommend a design pattern for intentARead-onlyIdempotent
Score curated design patterns against a free-text intent and recommend the top match.
Scores each entry in DESIGN_PATTERNS by domain match (weight 5) and
intent-keyword overlap (weight 1.5 per hit against intent.lower()),
then returns the top scorer plus up to three runners-up; makes no
call to Home Assistant.
Use when: turning a user's free-text card request into a concrete
pattern/template recommendation.
Not for: the full pattern body — call
card_builder_get_design_pattern(name) on the recommendation; the
underlying design rules — call card_builder_design_principles.
Returns: {intent, domain, entity_id, recommendation, score, label, description, ux_notes, recommended_template, anti_patterns, next_steps, alternatives}, or {..., "recommendation": None, "note": ...} when nothing scores above zero.
Inputs: intent (required), domain, entity_id. Returns: object
card_builder_design_principlesGet Card Builder design principlesARead-onlyIdempotent
Get the embedded UX design playbook for Card Builder cards.
Returns the static _DESIGN_PRINCIPLES_MD constant; makes no call to
Home Assistant.
Use when: deciding hierarchy, state feedback, spacing, typography, or
layout choices for a card, before or after using
card_builder_recipe_guide for the mechanics.
Not for: HOW to build the block tree itself — use
card_builder_recipe_guide.
Returns: markdown text covering hierarchy, state feedback via binding,
spacing rhythm, typography scale, semantic colors, layout choice
(grid vs flow vs absolute), state badges, background images, empty
states, and anti-patterns that produce flat-feeling cards.
Inputs: no named parameters. Returns: result
card_builder_get_block_schemaGet Card Builder block schemaARead-onlyIdempotent
Get the full embedded schema for one Card Builder block type.
Looks up block_type in the module-level BLOCK_TYPES constant and
adds its style targets from STYLE_TARGETS; makes no call to Home
Assistant.
Use when: checking a block's exact prop names, types, defaults, enum
values, and supported entity domains before writing a recipe.
Returns: {type, category, label, accepts_children, requires_entity, props, notes, supported_domains, style_targets, ...} — the same
entry as in BLOCK_TYPES plus style_targets.
Errors: {"error": "unknown_block_type", "block_type": ..., "known": [...]} when block_type isn't in the embedded schema.
Inputs: block_type (required). Returns: object
card_builder_get_cardGet Card Builder card by IDARead-onlyIdempotent
Get one Card Builder card by id, including its full config.
Fetches the whole card collection via card_builder/cards/list and
matches on id or the legacy card_id field client-side — there is no
dedicated get-by-id WebSocket command.
Use when: inspecting or copying one card's config before calling
card_builder_update_card or card_builder_renderer_card_config.
Returns: the matching card dict (same shape as one entry from
card_builder_list_cards).
Errors: {"error": "not_found", "card_id": ...} when no card matches.
Inputs: card_id (required). Returns: object
card_builder_get_card_templatePreview a card template configARead-onlyIdempotent
Resolve one built-in template into a full DocumentData config, without saving anything.
Calls the template's recipe function and, if it returned a recipe
shorthand rather than a full DocumentData, runs it through
card_builder_build_from_recipe. Makes no call to Home Assistant.
Use when: inspecting or hand-editing a template's config before
calling card_builder_create_card yourself.
Not for: saving the card directly — use
card_builder_make_template_card to skip this step.
Returns: the full DocumentData config dict for the template.
Errors: {"error": "unknown_template", "name": ..., "known": [...]}
when name isn't a known template.
Inputs: name (required), slot. Returns: object
card_builder_get_design_patternGet one design patternARead-onlyIdempotent
Get one curated design pattern by name, in full.
Looks up name in the module-level DESIGN_PATTERNS constant; makes
no call to Home Assistant.
Use when: reading the full rationale/anti-patterns for one pattern
already picked (e.g. via card_builder_design_for_intent).
Returns: same fields as one entry from
card_builder_list_design_patterns.
Errors: {"error": "unknown_pattern", "name": ..., "known": [...]}
when name isn't a known pattern.
Inputs: name (required). Returns: object
card_builder_get_style_snippetGet one style snippetARead-onlyIdempotent
Fetch one built-in style snippet wrapped in the full target/container envelope.
Looks up name in STYLE_SNIPPETS and wraps it as
{target: {containers: {container: <snippet>}}}; makes no call to
Home Assistant.
Use when: assigning exactly one snippet to a block's styles without
composing several via card_builder_build_styles.
Returns: {<target>: {containers: {<container>: <snippet>}}} — ready
to assign to a block's styles directly.
Errors: {"error": "unknown_snippet", "name": ..., "known": [...]}
when name isn't a known snippet.
Inputs: name (required), target, container. Returns: object
card_builder_list_block_typesList Card Builder block typesARead-onlyIdempotent
List every block type from the embedded Card Builder schema (BLOCK_TYPES).
Reads the module-level BLOCK_TYPES constant synced from upstream Card
Builder (see card_builder_check_schema_sync); makes no call to Home
Assistant.
Use when: discovering which block types exist before writing a recipe
for card_builder_build_from_recipe.
Not for: full prop details of one type — use
card_builder_get_block_schema.
Returns: list of {type, category, label, accepts_children, requires_entity, prop_count}, one entry per block type.
Inputs: category, include_internal. Returns: result
card_builder_list_button_toggle_featuresList button-toggle feature IDsARead-onlyIdempotent
List the feature IDs accepted by block-button-toggle / block-select-menu.
Reads the module-level FEATURE_DEFINITIONS constant; makes no call
to Home Assistant. Feature IDs are namespaced by domain — e.g.
climate_hvac_mode for an AC, cover_state for a blind, light_power
for a bulb.
Use when: picking an explicit feature value for a
block-button-toggle/block-select-menu prop instead of the default
"auto", which lets Card Builder pick the first available feature for
the entity at runtime.
Returns: list of {domain, id, label} dicts.
Inputs: domain. Returns: result
card_builder_list_cardsList Card Builder cardsARead-onlyIdempotent
List every Card Builder card stored on this Home Assistant instance.
Calls the card_builder/cards/list WebSocket command and returns the
raw collection: each entry carries id, name, description,
config (the DocumentData block tree), version, tags and
categories.
Use when: discovering existing cards before reading one in full with
card_builder_get_card or editing one with card_builder_update_card.
Returns: list of card dicts, in storage order, unfiltered.
Inputs: no named parameters. Returns: result
card_builder_list_card_templatesList built-in card templatesARead-onlyIdempotent
List built-in Card Builder recipe templates (CARD_RECIPES).
Reads the module-level CARD_RECIPES constant; makes no call to Home
Assistant.
Use when: browsing available templates before previewing one with
card_builder_get_card_template or instantiating it with
card_builder_make_template_card.
Returns: list of {name, label, description, domains} dicts.
Inputs: domain. Returns: result
card_builder_list_css_custom_propertiesList Card Builder CSS custom propertiesARead-onlyIdempotent
List every registered CSS custom property (@property registration).
Calls card_builder/css_custom_properties/list and returns the raw
collection: each entry has id, name, syntax (e.g. <color>),
initial_value and inherits.
Use when: checking which custom properties already exist before
registering a new one with
card_builder_create_css_custom_property.
Returns: list of CSS-custom-property dicts, unfiltered.
Inputs: no named parameters. Returns: result
card_builder_list_design_patternsList curated design patternsARead-onlyIdempotent
List curated UX design patterns, each pairing a recipe recommendation with the reasoning behind it.
Reads the module-level DESIGN_PATTERNS constant; makes no call to
Home Assistant.
Use when: browsing available design patterns before picking one by
hand, rather than letting card_builder_design_for_intent score them.
Returns: list of pattern dicts, each with name, intent_keywords,
domains, label, description, ux_notes,
recommended_template, anti_patterns.
Inputs: domain. Returns: result
card_builder_list_mediaList Card Builder media filesARead-onlyIdempotent
List files and folders in the Card Builder media directory.
Calls card_builder/media/list, scoped to www/card_builder/<path>.
Use when: checking what's already uploaded before calling
card_builder_upload_media or card_builder_delete_media.
Returns: dict with the media-browser entries HA's WS handler returns
for that path (files and sub-folders).
Inputs: path. Returns: object
card_builder_list_style_categoriesList Card Builder style categoriesARead-onlyIdempotent
List CSS style categories with their property names and unit conventions.
Reads the module-level STYLE_CATEGORIES constant; makes no call to
Home Assistant. Property names are camelCase (e.g.
flexDirection, backgroundColor) — anything else is silently
discarded by Card Builder's CSS resolver.
Use when: looking up the exact property names/units for a style
category before hand-writing a styles/dz_styles blob.
Not for: ready-to-use presets — use
card_builder_list_style_snippets.
Returns: list of {category, properties, length_units, legacy_aliases, notes} dicts.
Inputs: no named parameters. Returns: result
card_builder_list_style_presetsList Card Builder style presetsARead-onlyIdempotent
List every reusable Card Builder style preset.
Calls card_builder/style_presets/list and returns the raw
collection: each entry has id, name, description, data (the
CSS-style configuration blob) and, if present, extends_preset_id.
Use when: picking an existing preset to extend, or checking presets
before creating a new one with card_builder_create_style_preset.
Returns: list of style-preset dicts, unfiltered.
Inputs: no named parameters. Returns: result
card_builder_list_style_snippetsList built-in style snippetsARead-onlyIdempotent
List built-in Card Builder style snippets by name and style category.
Reads the module-level STYLE_SNIPPETS constant; makes no call to
Home Assistant.
Use when: browsing ready-made style presets (padding, flex layout,
typography scale) before composing them with
card_builder_build_styles.
Not for: the full property list per category — use
card_builder_list_style_categories; the full body of one snippet —
use card_builder_get_style_snippet.
Returns: list of {name, categories} dicts, where categories are
the style-category keys that snippet sets.
Inputs: no named parameters. Returns: result
card_builder_list_style_targetsList style targets for a block typeARead-onlyIdempotent
List the style targets (sub-components) one block type supports.
Looks up block_type in STYLE_TARGETS (defaulting to the single
"block" target); makes no call to Home Assistant. Example:
block-entity-field-state has state and unit targets so you can
colour the number and the unit differently.
Use when: styling a sub-component of a block (e.g. a slider's thumb)
rather than the whole block.
Returns: {block_type, targets} where targets is the list of valid
keys for that block's styles dict.
Errors: {"error": "unknown_block_type", "block_type": ...} when
block_type isn't in the embedded schema.
Inputs: block_type (required). Returns: object
card_builder_make_template_cardCreate card from templateA
Resolve a built-in template and save it as a new Card Builder card in one call.
Resolves template the same way as card_builder_get_card_template,
then passes the config straight to card_builder_create_card — which
assigns a new id server-side, so repeating this call creates a second,
distinct card.
Use when: turning a built-in template into a saved card without the
separate preview/create steps.
Not for: previewing the config first without saving — use
card_builder_get_card_template; a fully custom recipe — use
card_builder_build_from_recipe and card_builder_create_card
directly.
Returns: the created card dict, including its new id. Use that id
with card_builder_renderer_card_config(card_id, slot_entities= {<slot>: ...}) to place the card on a dashboard.
Errors: {"error": "unknown_template", "template": ..., "known": [...]} when template isn't a known template.
Inputs: name (required), template (required), slot, tags, +2 more. Returns: object
card_builder_recipe_guideGet Card Builder recipe guideARead-onlyIdempotent
Get the embedded how-to for building Card Builder cards programmatically.
Returns the static _RECIPE_GUIDE_MD constant; makes no call to Home
Assistant.
Use when: starting a card build and needing the DocumentData shape,
prop-wrapping rules, slots, or recipe shorthand before calling
card_builder_build_from_recipe.
Not for: UX/visual guidance — use card_builder_design_principles.
Returns: markdown text covering DocumentData layout, the block tree,
entity inheritance, slots, drop-zones, dashboard embedding, and the
recipe shorthand consumed by card_builder_build_from_recipe.
Inputs: no named parameters. Returns: result
card_builder_renderer_card_configBuild renderer card configARead-onlyIdempotent
Build the Lovelace card config dict that renders a Card Builder card.
Pure computation — assembles
{"type": "custom:card-builder-renderer-card", "card_id": ...} plus
the optional slot_entities/slot_actions keys; makes no call to
Home Assistant.
Use when: embedding an existing Card Builder card on a dashboard.
Not for: adding the resulting config to a dashboard — pass it as
card_config to dashboards_add_card_to_section (sections views) or
dashboards_add_card_to_view (masonry/panel views).
Returns: {"type": "custom:card-builder-renderer-card", "card_id": ..., "slot_entities": {...}, "slot_actions": {...}} — the latter two
keys are omitted when not provided.
Inputs: card_id (required), slot_actions, slot_entities. Returns: object
card_builder_update_cardUpdate Card Builder cardADestructive
Update fields of an existing Card Builder card.
Sends only the parameters that are not omitted to
card_builder/cards/update; every omitted parameter's prior value in
storage is left untouched, but any parameter that is supplied
(including config) fully replaces the previous value for that field
with no way to recover it afterwards.
Use when: renaming a card, editing its config, or retagging it.
Not for: creating a new card — use card_builder_create_card.
Returns: the updated card dict as returned by the WebSocket command.
Inputs: card_id (required), name, tags, config, +3 more. Returns: object
card_builder_update_style_presetUpdate Card Builder style presetADestructive
Update fields of an existing Card Builder style preset.
Sends only the parameters that are not omitted to
card_builder/style_presets/update; any parameter that is supplied
(including data) fully replaces the previous value for that field,
with no way to recover the prior value afterwards.
Use when: adjusting an existing preset's style data or metadata.
Not for: creating a new preset — use
card_builder_create_style_preset.
Returns: the updated style-preset dict as returned by the WebSocket
command.
Inputs: style_preset_id (required), data, name, description, +1 more. Returns: object
card_builder_upload_image_from_urlDownload and upload image from URLADestructiveIdempotent
Download an image from an http(s) URL and upload it to the Card Builder media library.
Only http/https schemes are accepted. The response must declare an
image/* Content-Type (covers image/svg+xml) and stay within
_MAX_URL_IMAGE_BYTES, else nothing is uploaded. image/svg+xml is
sanitized (see sanitize_svg) regardless of filename, since the
remote server controls the bytes. The file becomes public under
/local/ with no authentication, and an existing path/
filename is silently overwritten.
The URL and every redirect hop are resolved and rejected on a
loopback, link-local, unspecified, multicast or other reserved
address (incl. ::ffff:127.0.0.1) — host_network: true means
127.0.0.1/localhost here can reach host services that trust it as
a local peer. Private LAN ranges stay allowed (e.g. a camera snapshot
on your own network).
Use when: mirroring a remote image into the media library.
Not for: bytes already in memory — use card_builder_upload_media; a
file on disk — use card_builder_upload_media_from_path.
Returns: {reference, path, url}.
Errors: {"error": "scheme_not_allowed" | "target_not_allowed" | "dns_resolution_failed" | "too_many_redirects" | "content_type_not_allowed" | "file_too_large" | "download_failed" | "invalid_svg" | ...}.
Limits: 30-second timeout, _MAX_URL_IMAGE_BYTES (15 MiB) cap, up to
_MAX_URL_REDIRECTS (5) redirects, each re-validated.
Inputs: url (required), path, filename. Returns: object
card_builder_upload_mediaUpload media to Card Builder libraryADestructiveIdempotent
Upload base64-encoded bytes as a file in the Card Builder media directory.
Decodes content_base64 and writes it under www/card_builder/<path>/ <filename> via card_builder/media/upload. filename must be a bare
name (no /, \, or ..) with an allowed extension — .png,
.jpg, .jpeg, .gif, .webp, .svg, .avif (case-insensitive). A
.svg filename gets its decoded content sanitized (script/handler/
unsafe-URL stripping, element-count cap) — see sanitize_svg. The
file becomes public under /local/ with no authentication,
same origin as the HA frontend. Upstream's _write_media_file writes
with no existence check, so uploading onto an existing filename/
path silently overwrites it, with no backup.
Use when: the file bytes are already in memory (e.g. generated inline).
Not for: a file already on the HA config filesystem — use
card_builder_upload_media_from_path; a remote image — use
card_builder_upload_image_from_url; raw SVG you'd rather not
base64-encode — use card_builder_upload_svg.
Returns: {reference, path, url} — reference is the
cb-media://local/card_builder/<filename> URI for a block-image's
mediaReference prop.
Errors: {"error": "extension_not_allowed" | "invalid_base64" | "file_too_large" | "invalid_svg" | ...} (plus sanitize_svg errors)
when validation or sanitization rejects the input.
Limits: decoded content over _MAX_MEDIA_UPLOAD_BYTES (15 MiB) is
refused.
Inputs: filename (required), content_base64 (required), path. Returns: object
card_builder_upload_media_from_pathUpload local file to Card Builder mediaADestructiveIdempotent
Read a local file under the HA config directory and upload it as Card Builder media.
local_path must resolve (after following symlinks) under <config>/www
or <config>/media, and have an image/SVG extension — see
_ALLOWED_MEDIA_EXTENSIONS. Anything else (e.g. secrets.yaml,
/data/options.json, a sibling directory) is refused before the file is
read. .svg files are sanitized (script/event-handler/unsafe-URL
stripping) before upload — see sanitize_svg. The uploaded file
becomes public under Home Assistant's /local/ path with no
authentication. Upstream's _write_media_file writes with no
existence check, so uploading onto a path/filename that already
holds a file silently overwrites it, with no backup.
Use when: re-publishing a file that already exists on the config
filesystem (e.g. under www/) into the Card Builder media library.
Not for: bytes already in memory — use card_builder_upload_media; a
remote URL — use card_builder_upload_image_from_url.
Returns: {reference, path, url} on success, same shape as
card_builder_upload_media.
Errors: {"error": "invalid_path" | "path_not_allowed" | "extension_not_allowed" | "file_not_found" | "invalid_svg" | ...}
(plus the sanitize_svg errors) when the source path is outside the
allowed roots, has a disallowed extension, doesn't exist, or fails
sanitization.
Inputs: local_path (required), path, filename. Returns: object
card_builder_upload_svgUpload SVG markup to Card Builder mediaADestructiveIdempotent
Sanitize SVG markup and upload it to the Card Builder media directory.
svg_content must start with <svg or <?xml. .svg is appended to
filename if missing; the result is stored under
www/card_builder/<path>/<filename>. svg_content is always
sanitized first: <script>, <style>, <foreignObject>, <iframe>,
<embed>, <object> and other non-presentation elements are stripped
with their subtree, along with every on*= handler and any
href/xlink:href pointing at javascript: or an external/
data:image/svg+xml URL — see sanitize_svg for the allowlist. This
matters because the file becomes public, unauthenticated, under
/local/, where an unsanitized SVG opened directly executes embedded
script as stored XSS into an admin session. _write_media_file writes
with no existence check, so uploading onto an existing path/
filename silently overwrites it, with no backup.
Use when: publishing generated or hand-written SVG markup as media.
Not for: an SVG file on disk — use
card_builder_upload_media_from_path; a remote SVG URL — use
card_builder_upload_image_from_url.
Returns: {reference, path, url} — reference is the
cb-media://local/card_builder/<filename> URI for a block-image's
mediaReference prop.
Errors: {"error": "not_svg" | "file_too_large" | "path_not_allowed" | "svg_too_complex"} on invalid, unsafe, or oversized input.
Limits: capped at _MAX_MEDIA_UPLOAD_BYTES (15 MiB), then
_SVG_MAX_ELEMENTS elements after parsing.
Inputs: filename (required), svg_content (required), path. Returns: object
card_builder_validate_configValidate Card Builder configARead-onlyIdempotent
Run lightweight structural validation on a Card Builder config (DocumentData).
Checks version, rootId presence, that every block has a known
type, that parent/child links are mutually consistent, that
entity-required blocks resolve an entity provider (inherited, slot, or
fixed) by walking up the tree, and that prop values use the
{value: ...}/{binding: ...} wrapper Card Builder requires. Pure
computation — makes no call to Home Assistant and does not check
against the live upstream schema (see
card_builder_check_schema_sync for that).
Use when: sanity-checking a config before
card_builder_create_card/card_builder_update_card.
Returns: {ok: bool, errors: [...], warnings: [...], block_count, slot_count} — ok is false only when errors is non-empty;
warnings flags renamed/unwrapped/unknown props without failing.
Inputs: config (required). Returns: object
dashboards_add_card_to_sectionAdd card to dashboard sectionA
Insert a card into one section of a type: sections view, leaving every other view intact.
Resolves the view via _load_view, requires it to be a sections
view, inserts card_config into that section's cards list at
position (or the end), and saves the whole dashboard back. This is
the only way to make a card visible on a sections view —
dashboards_add_card_to_view writes to view.cards, which such a
view renders only in edit mode. When expected_config_hash is given,
it is checked against the dashboard's hash right after the read and
before any change, so a stale caller never overwrites the wrong
section.
Use when: adding a card to a specific section of a sections view.
Pass expected_config_hash whenever section_index/position came
from an earlier read that might now be stale.
Not for: a masonry/panel view — use
dashboards_add_card_to_view.
Returns: {status: "added", url_path, view_index, view_title, section_index, card_index, cards_in_section, config_hash} —
config_hash is re-read from HA after the save (not the locally built
dict), ready to chain into the next call's expected_config_hash.
Errors: raises ValueError when card_config has no type key, the
view can't be resolved, isn't a sections view, or section_index is
out of range. Returns {"error": "config_changed", "expected_config_hash", "current_config_hash", "action"} without saving when
expected_config_hash doesn't match.
Inputs: url_path (required), card_config (required), section_index (required), position, +2 more. Returns: object
dashboards_add_card_to_viewAdd card to dashboard viewA
Append a card to one view's cards list and save the whole dashboard.
Reads the dashboard via dashboards_get_dashboard_config, appends
card_config to views[view_index]["cards"] (creating that key if
absent), and writes the whole dashboard back with
dashboards_save_dashboard_config — every other view and card is
round-tripped unchanged.
Use when: adding a card to a masonry/panel view.
Not for: a type: sections view — there, cards in view.cards render
only in edit mode; use dashboards_add_card_to_section instead.
Returns: {"status": "saved", "url_path": ...} from the underlying
save.
Errors: raises ValueError when view_index is out of range for the
dashboard's view count.
Inputs: url_path (required), view_index (required), card_config (required). Returns: object
dashboards_add_dashboard_resourceAdd Lovelace resourceA
Register a custom JS or CSS resource that loads on every Lovelace dashboard page.
Sends url/resource_type to lovelace/resources/create, which
stores a new resource entry with a server-generated id — repeating
this call registers a second, distinct resource rather than updating
one. The tool itself only stores the URL string; it never fetches
url — the browser loads it later, from /local/ (incl. the
Marketplace's /local/community/), /hacsfiles/, or any external CDN
the URL names.
Use when: registering a custom card, theme, or script so it becomes
available on every dashboard.
Not for: changing an existing resource's URL/type — use
dashboards_update_dashboard_resource.
Returns: {"status": "added", "url": ..., "resource_type": ..., "result": ...} on success.
Errors: {"error": "resource_type must be 'module', 'js', or 'css'"}
when resource_type is anything else.
Inputs: url (required), resource_type. Returns: object
dashboards_add_section_to_viewAdd section to dashboard viewA
Insert a new section into a type: sections view.
Resolves the view via _load_view, requires it to be a sections
view, defaults section_config to {"type": "grid", "cards": []}
when omitted, inserts it into that view's sections list at
position (or the end), and saves the whole dashboard back. When
expected_config_hash is given, it is checked against the dashboard's
hash right after the read and before any change.
Use when: adding a whole new section (a card group with its own grid)
to a sections view, before populating it with
dashboards_add_card_to_section. Pass expected_config_hash whenever
position came from an earlier read that might now be stale.
Returns: {status: "added", url_path, view_index, view_title, section_index, sections_in_view, config_hash} — config_hash is
re-read from HA after the save, ready to chain into the next call's
expected_config_hash.
Errors: raises ValueError when section_config["cards"] isn't a
list, or the view can't be resolved/isn't a sections view. Returns
{"error": "config_changed", "expected_config_hash", "current_config_hash", "action"} without saving when
expected_config_hash doesn't match.
Inputs: url_path (required), position, view_index, section_config, +1 more. Returns: object
dashboards_add_view_to_dashboardAdd view to dashboardA
Append a new view to a dashboard and save the whole dashboard.
Reads the dashboard via dashboards_get_dashboard_config, appends
view_config to its views list, and writes the whole dashboard back
with dashboards_save_dashboard_config — every existing view and card
is round-tripped unchanged.
Use when: adding a whole new tab/view to a dashboard.
Not for: adding a card to an existing view — use
dashboards_add_card_to_view or dashboards_add_card_to_section.
Returns: {"status": "saved", "url_path": ...} from the underlying
save.
Inputs: url_path (required), view_config (required). Returns: object
dashboards_get_dashboard_configGet Lovelace dashboard configARead-onlyIdempotent
Get one Lovelace dashboard's config, or a read-only excerpt of one view.
Calls lovelace/config for url_path as a dashboard; if that raises
config_not_found, re-fetches the default dashboard and returns the
matching view instead, since url_path may instead be that view's own
path.
Use when: reading a dashboard's views/sections before editing it,
or inspecting one view without the surrounding dashboard.
Not for: passing the view-path result back into
dashboards_save_dashboard_config — that excerpt is not a full
dashboard config and would delete every other view.
Returns: the full dashboard dict (with views) for a dashboard
url_path; {"view": ..., "source": "default_dashboard_view", "path": ...} for a view path in the default dashboard.
Errors: raises RuntimeError when url_path matches neither a
dashboard nor a view in the default dashboard.
Inputs: url_path. Returns: object
dashboards_get_dashboard_resourcesGet Lovelace resourcesARead-onlyIdempotent
List every registered Lovelace resource (custom cards, CSS).
Calls lovelace/resources and returns the raw collection: each entry
has id, type (module/js/css), and url.
Use when: finding a resource's numeric id before calling
dashboards_update_dashboard_resource or
dashboards_remove_dashboard_resource.
Returns: list of resource dicts, unfiltered.
Inputs: no named parameters. Returns: result
dashboards_get_view_sectionsList sections of a dashboard viewARead-onlyIdempotent
List the sections of one type: sections view, with real indexes, headings and card counts.
Resolves the view via _load_view (dashboard config or default-
dashboard view path), requires it to be a sections view, and reports
each section's position, a fallback-derived heading (its heading
card, or title), and card count.
Use when: reading current section indexes before calling
dashboards_add_card_to_section / dashboards_update_card_in_section
/ dashboards_remove_card_from_section, or before re-sending
expected_config_hash to one of them after their previous call
changed it.
Returns: {status, url_path, view_index, view_title, view_path, sections: [{section_index, heading, card_count}, ...], config_hash} —
pass config_hash back as expected_config_hash to
dashboards_add_card_to_section / _update_card_in_section /
_remove_card_from_section / _add_section_to_view to detect a
dashboard change before your write lands.
Errors: raises ValueError when the view can't be resolved (bad
index/path) or is not a type: sections view.
Inputs: url_path, view_index. Returns: object
dashboards_list_dashboardsList Lovelace dashboardsARead-onlyIdempotent
List every registered Lovelace dashboard.
Calls lovelace/dashboards/list and returns the raw collection: each
entry has id, url_path, title, mode (storage or yaml), and
related flags.
Use when: discovering a dashboard's url_path before calling
dashboards_get_dashboard_config or dashboards_screenshot.
Returns: list of dashboard dicts, unfiltered. The default dashboard is
not included — it has no url_path entry here.
Inputs: no named parameters. Returns: result
dashboards_remove_card_from_sectionRemove card from dashboard sectionADestructive
Delete one card from a section of a type: sections view.
Resolves the view and section via _load_view/_require_section,
pops the card at card_index from that section's cards list, and
saves the whole dashboard back. card_index is a position, not a
stable id — repeating this call with the same section_index/
card_index after a first successful removal deletes whatever card
has shifted into that position next, not a no-op, unless
expected_config_hash is also passed and now points at the pre-removal
hash, in which case the repeat is rejected with config_changed
instead of deleting the wrong card.
Use when: removing a card that's no longer wanted on a sections view.
Pass expected_config_hash whenever section_index/card_index came
from an earlier read that might now be stale.
Returns: {status: "removed", url_path, view_index, view_title, section_index, card_index, removed_card, cards_in_section, config_hash} — removed_card can be passed back to
dashboards_add_card_to_section to restore it; config_hash is
re-read from HA after the save, ready to chain into the next call's
expected_config_hash.
Errors: raises ValueError when the view/section/card can't be
resolved (bad index/path). Returns {"error": "config_changed", "expected_config_hash", "current_config_hash", "action"} without
saving when expected_config_hash doesn't match.
Inputs: url_path (required), card_index (required), section_index (required), view_index, +1 more. Returns: object
dashboards_remove_dashboard_resourceRemove Lovelace resourceADestructiveIdempotent
Remove a registered Lovelace resource by its numeric id.
Requires confirm=True; without it, returns a confirmation prompt and
makes no change. With confirm=True, calls lovelace/resources/delete,
which drops the resource from every dashboard page that loaded it —
any custom card/theme it provided stops rendering until the resource
is re-added.
Use when: removing a resource that is no longer needed (e.g. after
uninstalling a HACS / Marketplace frontend card).
Returns: {"status": "removed", "resource_id": ..., "result": ...} on
success.
Errors: {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false.
Inputs: resource_id (required), confirm. Returns: object
dashboards_save_dashboard_configSave Lovelace dashboard configADestructiveIdempotent
Replace the entire config of one storage-mode Lovelace dashboard.
Sends config as-is to lovelace/config/save, fully overwriting that
dashboard's stored views/sections with no validation, backup, or
undo — keep the previous config (e.g. from
dashboards_get_dashboard_config) if you need to restore it.
Use when: writing back a dashboard object built or fetched in full.
Not for: a single card or section change — use
dashboards_add_card_to_section/dashboards_update_card_in_section/
dashboards_remove_card_from_section (sections views) or
dashboards_add_card_to_view (masonry/panel views), which read-modify-
write the config for you.
Returns: {"status": "saved", "url_path": ...}.
Inputs: config (required), url_path. Returns: object
dashboards_screenshotScreenshot a Lovelace dashboard viewARead-onlyIdempotent
Capture a PNG screenshot of one Lovelace dashboard view via the Puppet add-on engine.
Resolves url_path to a concrete frontend route (see the parameter
description), rejects paths containing unsafe characters, then calls
the Puppet engine (discovered via Supervisor or
NEXUS_SCREENSHOT_ENGINE_URL) over HTTP with the resolved viewport/
zoom/wait parameters and returns its PNG response as base64. Deciding
between a dashboard route and a default-dashboard view path costs one
lovelace/dashboards/list call (skipped when url_path already
starts with lovelace). Reaches only a local/LAN add-on, not the
public internet.
Use when: visually verifying a dashboard or view after editing it.
Returns: {url_path, engine, format: "png", width, height, image_base64, size_bytes} on success — url_path echoes the
resolved route, not the raw argument, and image_base64 can be large,
especially with full_page=True (fixed 4096px height).
Errors: {"error": "dashboard_list_unavailable" | "invalid_path" | "engine_not_available" | "engine_unreachable" | "engine_http_<code>" | "empty_response", "detail": ..., ...} when the dashboard list can't
be fetched, the path is unsafe, the Puppet engine isn't installed/
started, or the engine request itself fails.
Limits: 60-second engine timeout; full_page=True only approximates
full-scroll capture since the engine does not measure actual page
height, so it can crop tall pages or leave blank space on short ones.
Inputs: zoom, width, height, wait_ms, +2 more. Returns: object
dashboards_update_card_in_sectionUpdate card in dashboard sectionADestructive
Change one existing card inside a section of a type: sections view.
Resolves the view and target card via _load_view/_require_card,
then merges card_config's keys into the existing card (merge=True,
the default) or replaces it outright (merge=False), and saves the
whole dashboard back. The previous card is only recoverable via
card_before in this call's own response — storage itself keeps no
history. With expected_config_hash, the dashboard's hash is checked
right after the read and before any change, so a stale caller can't
edit the wrong card.
Use when: tweaking or replacing one card already placed in a section.
Pass expected_config_hash when section_index/card_index came
from a read that might now be stale.
Not for: adding a new card — use
dashboards_add_card_to_section; removing one — use
dashboards_remove_card_from_section.
Returns: {status: "updated", url_path, view_index, view_title, section_index, card_index, card_before, card_after, config_hash} —
config_hash is re-read from HA after the save, for the next call's
expected_config_hash.
Errors: raises ValueError when card_config is empty, merge=False
lacks a type key, or the view/section/card can't be resolved.
Returns {"error": "config_changed", ...} without saving when
expected_config_hash doesn't match.
Inputs: url_path (required), card_index (required), card_config (required), section_index (required), +3 more. Returns: object
dashboards_update_dashboard_resourceUpdate Lovelace resourceADestructiveIdempotent
Replace the URL and type of an existing Lovelace resource.
Sends resource_id, url and resource_type to
lovelace/resources/update, replacing both fields of that resource
entry — the previous URL/type are not recoverable afterwards. Like
dashboards_add_dashboard_resource, this tool never fetches url
itself.
Use when: repointing an existing resource entry at a new file or
changing its declared type.
Not for: registering a brand-new resource — use
dashboards_add_dashboard_resource.
Returns: {"status": "updated", "resource_id": ..., "url": ..., "resource_type": ..., "result": ...} on success.
Errors: {"error": "resource_type must be 'module', 'js', or 'css'"}
when resource_type is anything else.
Inputs: url (required), resource_id (required), resource_type. Returns: object
devices_list_devicesList devices (slim fields)ARead-onlyIdempotent
List all devices with a slimmed set of common fields.
Calls WS config/device_registry/list and projects each entry down to
id, name_by_user, name, area_id, manufacturer, model, entry_type, plus
config_entries and disabled_by when present.
Use when: you need the device registry without every raw field.
Not for: the full unfiltered registry — use areas_list_devices;
devices scoped to one area — use devices_list_devices_in_area; fuzzy
name-based search — use search_search_devices.
Returns: list of slimmed device dicts as described above.
Inputs: no named parameters. Returns: result
devices_list_devices_in_areaList devices in areaARead-onlyIdempotent
List devices currently assigned to one area.
Calls WS config/device_registry/list and filters the slimmed device
list (see devices_list_devices) down to entries whose area_id
matches.
Use when: you need only the devices in one area rather than the whole
registry.
Not for: the whole device registry — use devices_list_devices or
areas_list_devices; fuzzy name-based search — use
search_search_devices.
Returns: list of slimmed device dicts (see devices_list_devices) whose
area_id equals the given area_id.
Limits: devices without an area are never returned here.
Inputs: area_id (required). Returns: result
devices_remove_deviceRemove device from config entryADestructiveIdempotent
Remove a device from Home Assistant after checking it belongs to the given config entry.
Reads the device registry and refuses unless the device belongs to
config_entry_id, then sends WS config/device_registry/remove
(HA 2026.x); on an HA without that command it sends the older
config/device_registry/remove_config_entry. The integration must
support device removal (HA asks it first), otherwise HA refuses.
Use when: removing a stale device an integration no longer provides.
Not for: renaming, moving or disabling it — use devices_update_device.
Returns: {"removed": true, "device_id", "config_entry_id", "command"}.
Errors: device_not_found, config_entry_not_in_device (no removal
sent), ws_error with Home Assistant's code/message (e.g. the
integration rejected the removal).
Limits: config_entry_id is required as a safety check even though
HA 2026.x removes the device as a whole.
Inputs: device_id (required), config_entry_id (required). Returns: object
devices_update_deviceUpdate device registry entryADestructive
Update fields on an existing device registry entry.
Calls WS config/device_registry/update; only the parameters you pass
are sent, so omitted or null fields are left unchanged.
Use when: renaming a device, moving it to another area, or enabling or
disabling it.
Returns: dict with device_id and result (the updated device,
slimmed like devices_list_devices).
Limits: area_id can only be set here, not cleared — there is no
parameter to remove an existing area assignment.
Inputs: device_id (required), area_id, disabled_by, name_by_user. Returns: object
discover_get_tool_docGet full documentation for one toolARead-onlyIdempotent
Get one tool's full description, parameter schema and MCP annotations.
Looks the tool up by exact name in the current index and returns its
full (un-truncated) docstring alongside the same inputSchema and
annotations an MCP client sees from tools/list.
Use when: reading a specific tool's full contract after finding its
name with discover_tool_search.
Not for: searching by keyword — use discover_tool_search.
Returns: {"name", "namespace", "description", "input_schema", "annotations", "access"}. input_schema is the tool's JSON-schema
parameter dict; annotations is the four MCP hints plus title as a
plain dict, or None for a tool whose module has not yet declared them.
access is "read", "write" or "destructive" (ADR-0002/0003
annotation class), computed fail-closed even when annotations is
None.
Errors: {"error": "not_found", "name": name} when no tool with that
exact name is in the index.
Inputs: name (required). Returns: object
discover_list_namespacesList tool namespacesARead-onlyIdempotent
List every mounted Nexus tool namespace with its tool count.
Groups the current tool index by namespace (the mount prefix parsed
from server.py, e.g. "card_builder", "entities") and counts entries.
Use when: getting an overview of which domains exist before narrowing a
discover_tool_search call with its namespace parameter.
Not for: the tools within one namespace — use discover_tool_search
with that namespace.
Returns: list of {"namespace", "count"}, most populated first.
Inputs: no named parameters. Returns: result
discover_refresh_indexRebuild the tool search indexARead-onlyIdempotent
Force-rebuild the in-memory tool search index.
Drops the cached index and rebuilds it from _ROOT.list_tools(). Only
nexus's own in-process cache is affected — nothing in HA changes.
Use when: tools were mounted or changed at runtime after the index was
first built (normally only relevant during development, since
server.py mounts every namespace once at startup).
Not for: routine searches — discover_tool_search/
discover_list_namespaces/discover_get_tool_doc already rebuild the
index lazily on first use.
Returns: {"status": "rebuilt", "tools": <count>}.
Inputs: no named parameters. Returns: object
discover_tool_searchSearch the tool catalogueARead-onlyIdempotent
Fuzzy search the Nexus tool catalogue by name and description.
Scores every mounted tool's name + description against query with a
BM25-lite ranking (term frequency/inverse document frequency plus a
small boost when a query word appears in the tool name itself) and
returns the top top_k matches.
Use when: finding the right tool name before calling it, instead of
keeping the whole tool surface in working memory.
Not for: a single tool's full documentation once you have its name —
use discover_get_tool_doc.
Returns: list of {"name", "namespace", "summary", "score", "access"}
dicts, highest score first; empty list if nothing scores above zero.
access is "read", "write" or "destructive" (ADR-0002/0003
annotation class).
Inputs: query (required), top_k, namespace. Returns: result
energy_add_battery_sourceAdd battery sourceA
Add a battery source to the Energy Dashboard.
Reads the current preferences, appends a new {"type": "battery", ...}
entry combining stat_energy_from (discharge) and stat_energy_to
(charge) to the energy_sources list, and saves it via WS
energy/save_prefs. Calling it twice with the same arguments adds a
second, duplicate source.
Use when: registering a home battery's charge and discharge sensors as
one Energy Dashboard source.
Not for: grid or solar sources — use energy_add_grid_consumption/
energy_add_grid_return/energy_add_solar_source.
Returns: {"status": "added", "stat_energy_from": ..., "stat_energy_to": ..., "result": ...}.
Errors: {"error": str(e)} when either WS call raises.
Inputs: stat_energy_to (required), stat_energy_from (required). Returns: object
energy_add_grid_consumptionAdd grid consumption flowA
Add a grid consumption flow to the Energy Dashboard's grid source.
Reads the current preferences via ha._ws_call("energy/get_prefs"),
appends stat_energy_from (and stat_cost if given) as a new
flow_from entry on the existing grid source, creating that grid
source first if none exists yet, then saves the updated list via WS
energy/save_prefs. Calling it twice with the same stat_energy_from
adds a second, duplicate flow entry.
Use when: registering a grid-import sensor as an Energy Dashboard
consumption flow.
Not for: grid export/solar compensation — use
energy_add_grid_return; for a full source-list replacement use
energy_save_energy_prefs.
Returns: {"status": "added", "stat_energy_from": ..., "result": ...}.
Errors: {"error": str(e), "stat_energy_from": ...} when either WS call
raises.
Inputs: stat_energy_from (required), stat_cost. Returns: object
energy_add_grid_returnAdd grid return flowA
Add a grid return (export) flow to the Energy Dashboard's grid source.
Reads the current preferences via ha._ws_call("energy/get_prefs"),
appends stat_energy_to (and stat_compensation if given) as a new
flow_to entry on the existing grid source, creating that grid source
first if none exists yet, then saves via WS energy/save_prefs. Calling
it twice with the same stat_energy_to adds a second, duplicate entry.
Use when: registering a solar-export or other grid-return sensor, e.g.
solar sold back to the grid.
Not for: grid import — use energy_add_grid_consumption; for a full
source-list replacement use energy_save_energy_prefs.
Returns: {"status": "added", "stat_energy_to": ..., "result": ...}.
Errors: {"error": str(e), "stat_energy_to": ...} when either WS call
raises.
Inputs: stat_energy_to (required), stat_compensation. Returns: object
energy_add_solar_sourceAdd solar production sourceA
Add a solar production source to the Energy Dashboard.
Reads the current preferences, appends a new {"type": "solar", ...}
entry to the energy_sources list, and saves it via WS
energy/save_prefs. Calling it twice with the same stat_energy_from
adds a second, duplicate source.
Use when: registering a solar production sensor as a new Energy
Dashboard source.
Not for: an existing source's export flow — use
energy_add_grid_return; for a full source-list replacement use
energy_save_energy_prefs.
Returns: {"status": "added", "stat_energy_from": ..., "result": ...}.
Errors: {"error": str(e), "stat_energy_from": ...} when either WS call
raises.
Inputs: stat_energy_from (required), config_entry_solar_forecast. Returns: object
energy_get_energy_infoGet energy dashboard infoARead-onlyIdempotent
Return Energy Dashboard info such as cost sensors and currency.
Calls the WebSocket endpoint energy/info and returns its payload
unchanged.
Use when: you need metadata about the Energy Dashboard (available cost
sensor types, currency) rather than the source configuration itself.
Not for: the actual source/device list — use energy_get_energy_prefs.
Returns: dict as returned by HA's energy/info WS command.
Errors: {"error": str(e)} when the WS call raises.
Inputs: no named parameters. Returns: object
energy_get_energy_prefsGet energy dashboard preferencesARead-onlyIdempotent
Return the full HA Energy Dashboard preferences.
Calls the WebSocket endpoint energy/get_prefs and returns its payload
unchanged, including the configured energy_sources and
device_consumption lists.
Use when: you need the current preferences before editing them with
energy_save_energy_prefs or one of the energy_add_*/
energy_remove_energy_source helpers.
Not for: adding or removing a single source without hand-building the
full list — use energy_add_grid_consumption, energy_add_grid_return,
energy_add_solar_source, energy_add_battery_source or
energy_remove_energy_source instead.
Returns: dict with energy_sources (list) and device_consumption
(list), exactly as HA stores them.
Errors: {"error": "..."} when the WebSocket call raises.
Inputs: no named parameters. Returns: object
energy_remove_energy_sourceRemove energy sourceADestructiveIdempotent
Remove an energy source identified by its stat_energy_from.
Reads the current preferences, drops any solar/battery/gas/water source
whose stat_energy_from matches, also strips matching flow_from
entries from the grid source, and saves the resulting list via WS
energy/save_prefs. This replaces the whole energy_sources list with
one that has the matching entries removed — anything else in the list
is preserved as-is.
Use when: undoing an energy_add_solar_source/energy_add_battery_source/
energy_add_grid_consumption call, or dropping a source that no longer
exists.
Not for: replacing the whole source list at once — use
energy_save_energy_prefs.
Returns: {"status": "removed", "removed": <count>, "stat_energy_from": ..., "result": ...} on success, or {"status": "not_found", "stat_energy_from": ...} when nothing matched.
Errors: {"error": str(e), "stat_energy_from": ...} when either WS call
raises.
Inputs: stat_energy_from (required). Returns: object
energy_save_energy_prefsReplace energy dashboard source listsADestructiveIdempotent
Save Energy Dashboard preferences via WS energy/save_prefs.
Each of energy_sources/device_consumption you pass replaces the
entire corresponding saved list — it is not merged with what's already
there. Use energy_add_grid_consumption, energy_add_grid_return,
energy_add_solar_source, energy_add_battery_source or
energy_remove_energy_source for incremental edits instead of
hand-building the full list. currency/energy_per_unit are kept only
for backward compatibility and are rejected: HA's currency lives in core
config (homeassistant.currency), not this WS schema, and
energy_per_unit does not exist in it at all.
Use when: you already hold the full desired energy_sources/
device_consumption list, e.g. from energy_get_energy_prefs.
Not for: adding or removing one source — use the energy_add_*/
energy_remove_energy_source helpers, which read-modify-write for you.
Returns: {"status": "saved", "result": ..., "fields": [...]} on
success.
Errors: {"error": "no fields to save", ...} when both list parameters
are omitted; {"error": "currency and energy_per_unit are not fields of HA's energy/save_prefs WS schema...", ...} when either deprecated
parameter is passed; {"error": str(e), ...} when the WS call raises.
Inputs: currency, energy_sources, energy_per_unit, device_consumption. Returns: object
energy_validate_energy_prefsValidate energy dashboard configurationARead-onlyIdempotent
Validate the currently saved Energy Dashboard configuration.
Calls the WebSocket endpoint energy/validate, which checks the saved
energy_sources/device_consumption for issues (e.g. a statistic ID
that no longer exists) without changing anything.
Use when: checking whether the current Energy Dashboard setup has
issues, e.g. after editing sources with energy_save_energy_prefs or
one of the energy_add_* helpers.
Not for: reading the configuration itself — use
energy_get_energy_prefs.
Returns: dict as returned by HA's energy/validate WS command, listing
any detected issues per source.
Errors: {"error": str(e)} when the WS call raises.
Inputs: no named parameters. Returns: object
entities_assign_entity_to_areaAssign entity to areaADestructiveIdempotent
Assign an entity to an area, replacing its current area assignment.
Calls WS config/entity_registry/update with area_id=area_id; any
previous area assignment is overwritten and not returned.
Use when: moving an entity to a different area in the registry.
Not for: renaming it, or toggling exposure — use
entities_update_entity_name or entities_set_entity_exposure.
Returns: the updated entity registry entry from Home Assistant.
Inputs: area_id (required), entity_id (required). Returns: object
entities_bulk_controlBulk turn on, off or toggle entitiesA
Turn on, turn off or toggle many entities in one call, grouped by domain.
Groups entity_ids by domain and issues one <domain>.<action> service
call per domain group (e.g. all light.* entities get a single
light.turn_on), instead of one call per entity.
Use when: applying the same on/off/toggle action to many entities across
domains at once.
Not for: writing arbitrary states instead of calling a service — use
entities_bulk_set_state; controlling every entity of one domain in a
single area by area_id rather than an explicit entity_id list — use
areas_control_area.
Returns: dict mapping domain to the number of entities affected.
Errors: raises ValueError when action is not one of turn_on,
turn_off, toggle.
Inputs: action (required), entity_ids (required). Returns: object
entities_bulk_set_entity_exposureBulk set entity assistant exposureAIdempotent
Expose or hide many entities across one or more voice assistants in a single call.
Calls WS homeassistant/expose_entity once with the full entity_ids
and assistants lists, which HA accepts natively, instead of one call
per entity/assistant pair. Returns immediately with an empty result when
entity_ids is empty.
Use when: changing exposure for many entities and/or several assistants
at once.
Not for: a single entity and assistant — use
entities_set_entity_exposure.
Returns: dict with count, assistants, should_expose and the raw WS
result.
Errors: raises ValueError when assistants contains an identifier
outside conversation, cloud.alexa, cloud.google_assistant.
Inputs: entity_ids (required), should_expose (required), assistants. Returns: object
entities_bulk_set_stateBulk write virtual entity statesAIdempotent
Write states for many entities directly via the states API, one call per entity.
Calls ha.set_state(entity_id, state, attributes) per item in
updates, which posts to /api/states/<entity_id>; this sets a virtual
state that a real device driver overwrites on its next update, unlike a
real service call.
Use when: seeding or overriding state for testing, template sensors, or
entities with no backing device.
Not for: actually controlling a device — use entities_bulk_control.
Returns: list of per-update dicts ({entity_id, ok, error?, error_type?});
a missing entity_id/state or a failed write is reported per item, not
raised.
Errors: per-item {"ok": false, "error": "...", "error_type": "..."};
error_type is "validation" for a missing entity_id/state (no
write attempted), "http" for an httpx.HTTPError from the write call
(bad response or network failure talking to Home Assistant), or
"unexpected" for any other exception. An "unexpected" error is still
caught per item and does not abort the rest of the batch.
Inputs: updates (required). Returns: result
entities_disable_entityDisable entity in registryAIdempotent
Disable an entity in the registry so Home Assistant stops creating its state.
Calls WS config/entity_registry/update with disabled_by="user".
Use when: retiring an entity without deleting its registry entry.
Not for: re-enabling it — use entities_enable_entity.
Returns: the updated entity registry entry from Home Assistant.
Inputs: entity_id (required). Returns: object
entities_enable_entityEnable entity in registryAIdempotent
Re-enable a previously disabled entity in the registry.
Calls WS config/entity_registry/update with disabled_by=None.
Use when: restoring an entity disabled via entities_disable_entity.
Not for: disabling it — use entities_disable_entity.
Returns: the updated entity registry entry from Home Assistant.
Inputs: entity_id (required). Returns: object
entities_get_entityGet entity stateARead-onlyIdempotent
Get the full state and attributes of a single entity.
Calls ha.get_state(entity_id), a single HTTP GET to
/api/states/<entity_id>; the response includes state, attributes,
last_changed and last_updated as reported by Home Assistant.
Use when: inspecting one entity's current value and attributes before or
after an action.
Not for: many entities at once — use entities_list_entities or
snapshot_get_snapshot.
Returns: dict with entity_id, state, attributes, last_changed,
last_updated, context.
Inputs: entity_id (required). Returns: object
entities_get_entity_exposureGet entity voice assistant exposureARead-onlyIdempotent
Get exposure flags for one entity across all voice assistants.
Home Assistant has no per-entity exposure query, so this fetches the
full exposure map via WS homeassistant/expose_entity/list and filters
it client-side; an entity absent from that map is reported as False
for every assistant.
Use when: checking whether one entity is exposed, and to which
assistants.
Not for: the whole exposure map for one assistant — use
entities_list_exposed_entities.
Returns: dict with entity_id and exposure (assistant name -> bool for
conversation, cloud.alexa, cloud.google_assistant).
Inputs: entity_id (required). Returns: object
entities_list_entitiesList entities with filtersARead-onlyIdempotent
List entity states, optionally filtered by domain, with pagination and field selection.
Reads live states via ha.get_states() over HTTP; when fields requests
area_id, device_id or labels, it also fetches the entity registry
over WebSocket and joins it by entity ID. Filtering by domain and
pagination (limit/offset) are applied client-side after the fetch.
Use when: browsing or searching current entity states across the whole
installation or one domain.
Not for: raw registry fields such as disabled/hidden status — use
entities_list_entity_registry; a plain unfiltered state dump — use
ws_get_states.
Returns: list of dicts, one per entity, containing only the requested
fields.
Limits: limit/offset paginate the already-filtered list; no size cap
beyond that.
Inputs: limit, domain, fields, offset. Returns: result
entities_list_entity_registryList entity registry entriesARead-onlyIdempotent
Get the raw entity registry, including disabled and hidden entities.
Calls WS config/entity_registry/list and filters client-side by
domain when given. Unlike entities_list_entities, this has no state
values, only registry metadata (area_id, device_id, disabled_by,
labels, ...).
Use when: auditing registry metadata, including disabled/hidden entities
that carry no live state.
Not for: current state values — use entities_list_entities.
Returns: list of raw entity registry entry dicts from Home Assistant.
Inputs: domain. Returns: result
entities_list_exposed_entitiesList entities exposed to an assistantARead-onlyIdempotent
List every entity currently exposed to one voice assistant.
Home Assistant has no per-assistant exposure query, so this fetches the
full exposure map via WS homeassistant/expose_entity/list and filters
it client-side for the given assistant.
Use when: auditing what one assistant can currently see.
Not for: exposure of one specific entity — use
entities_get_entity_exposure.
Returns: dict with assistant and exposed (list of entity IDs).
Errors: raises ValueError when assistant is not one of conversation,
cloud.alexa, cloud.google_assistant.
Inputs: assistant (required). Returns: object
entities_remove_entityRemove entity from registryADestructiveIdempotent
Remove an entity's entry from the entity registry, refusing one an integration still provides.
Reads the entry (config/entity_registry/get) and the entity's state.
An entity counts as still provided when it has a state that is not a
restored placeholder (attributes.restored, which HA sets for entities
no loaded integration provides). Such an entity is refused unless
force, because its integration re-creates the entry at the next
reload. Otherwise sends config/entity_registry/remove; its customised
name, area, labels and entity_id are lost.
Use when: cleaning up orphaned entities ("no longer provided").
Not for: hiding a working entity — use entities_disable_entity;
removing a device with its entities — use devices_remove_device.
Returns: {"removed": true, "entity_id", "platform", "was_provided"}.
Errors: invalid_entity_id (no I/O), not_found,
entity_still_provided (nothing removed), state_check_failed,
ws_error with Home Assistant's code/message.
Inputs: entity_id (required), force. Returns: object
entities_select_optionSelect entity optionAIdempotent
Select an option on an input_select or select entity.
Calls input_select.select_option for input_select.* entities, or
select.select_option for every other domain (in practice select.*).
Use when: setting the current option of an input_select or select entity.
Not for: an input_select-only call site — helpers_set_input_select
does the same thing for that domain specifically.
Returns: the list of changed states from Home Assistant.
Inputs: option (required), entity_id (required). Returns: result
entities_set_entity_exposureSet entity voice assistant exposureAIdempotent
Expose or hide one entity to one voice assistant.
Calls WS homeassistant/expose_entity with a single-element
entity_ids/assistants list.
Use when: changing exposure for one entity and one assistant.
Not for: many entities or assistants at once — use
entities_bulk_set_entity_exposure.
Returns: dict with entity_id, assistant, should_expose and the raw
WS result.
Errors: raises ValueError when assistant is not one of conversation,
cloud.alexa, cloud.google_assistant.
Inputs: assistant (required), entity_id (required), should_expose (required). Returns: object
entities_set_valueSet entity valueAIdempotent
Set the numeric value of an input_number, number or climate entity.
Dispatches to input_number.set_value, number.set_value or
climate.set_temperature depending on entity_id's domain; any other
domain raises ValueError before any HTTP call is made.
Use when: writing a target number or temperature to one of these three
domains.
Not for: input_text, input_select, input_boolean or input_datetime — use
helpers_set_input_text, helpers_set_input_select,
helpers_set_input_boolean or helpers_set_input_datetime.
Returns: the list of changed states from Home Assistant.
Errors: raises ValueError for any domain other than input_number,
number or climate.
Inputs: value (required), entity_id (required). Returns: result
entities_toggleToggle an entityA
Toggle an entity between on and off by calling its domain's toggle action.
Calls <domain>.toggle with {"entity_id": entity_id} over HTTP; the
resulting state depends on the entity's current state, so repeating this
call flips it back and forth.
Use when: the desired end state is unknown or irrelevant, only "flip it".
Not for: a deterministic on/off — use entities_turn_on/entities_turn_off.
Returns: the list of changed states from Home Assistant.
Inputs: entity_id (required). Returns: result
entities_turn_offTurn off an entityAIdempotent
Turn off an entity by calling its domain's turn_off action.
Calls <domain>.turn_off with {"entity_id": entity_id} over HTTP.
Use when: turning off any controllable entity regardless of domain.
Not for: flipping state without knowing the target — use
entities_toggle.
Returns: the list of changed states from Home Assistant.
Inputs: entity_id (required). Returns: result
entities_turn_onTurn on an entityAIdempotent
Turn on an entity, optionally with light-only color and brightness options.
Calls <domain>.turn_on for the entity's domain over HTTP. If any of
brightness, color_temp, color_temp_kelvin or rgb_color is given
for a non-light entity, the service is not called at all — HA's own
turn_on for other domains (e.g. switch) rejects unknown fields, so
this checks the domain first. A given color_temp (mireds) is converted
to Kelvin (round(1_000_000 / mireds)) since HA's light.turn_on no
longer accepts mireds.
Use when: turning on any entity, with or without light color/brightness.
Not for: a dedicated light color/brightness change without an on/off
intent — use services_set_light_color; an input_boolean-only helper —
helpers_set_input_boolean is the domain-specific equivalent.
Returns: the list of changed states from Home Assistant, or an error
dict.
Errors: {"error": "..."} when a light-only option is given for a
non-light domain.
Inputs: entity_id (required), rgb_color, brightness, color_temp, +1 more. Returns: result
entities_update_entity_nameRename entity in registryADestructiveIdempotent
Rename an entity in the entity registry, replacing its current display name.
Calls WS config/entity_registry/update with name=name; the previous
name is not returned or preserved anywhere by this call.
Use when: correcting or customising an entity's display name.
Not for: reassigning area, or enabling/disabling — use
entities_assign_entity_to_area, entities_disable_entity,
entities_enable_entity.
Returns: the updated entity registry entry from Home Assistant.
Inputs: name (required), entity_id (required). Returns: object
esphome_clean_mqttClean stale MQTT discovery entriesADestructiveIdempotent
Remove stale MQTT discovery entries for an ESPHome device, through HA's own MQTT integration.
Skips with zero network calls when the config has no mqtt: section.
Otherwise resolves the node name (esphome.name, with substitutions:)
and mqtt.discovery_prefix (default "homeassistant"). With a matching
HA device, reads topics via WS mqtt/device/debug_info; otherwise
briefly mqtt/subscribes to {prefix}/+/{node_name}/# and collects
retained topics. Clears each topic via the mqtt.publish service,
payload="" and retain=True -- MQTT's own way to delete a retained
message. Never touches the ESPHome dashboard, which has no
MQTT-topic-clearing command.
Use when: a removed/renamed device's old MQTT discovery entries still
linger in Home Assistant.
Not for: a config with no mqtt: section; firmware artifacts -- use
esphome_compile_device.
Returns: {"device", "action": "clean_mqtt", "skipped": True, "reason": ...} with no mqtt: section; otherwise {"success": <bool>, "method": "debug_info"|"wildcard_subscribe", "topics_cleared": [...], "count": <int>}, plus "errors": [...] on partial failures.
Errors: {"error": "..."} for an invalid/missing device file, an
unresolvable esphome.name/mqtt.discovery_prefix, or a WebSocket/
service-call failure.
Limits: the wildcard fallback only collects for min(timeout, 3)
seconds -- may miss a slow message or catch an unrelated topic.
Inputs: name (required), timeout, log_lines. Returns: object
esphome_compile_deviceCompile ESPHome firmwareAIdempotent
Compile ESPHome firmware for a device via the dashboard's /compile WebSocket route.
Blocks until the compile process exits (~60-180s). Compatible with the
"ESPHome Device Builder" add-on (esphome/device-builder): /compile
keeps the same spawn wire protocol as the old dashboard, now backed by
its firmware job queue. A first build for a platform fetches PlatformIO
packages from the internet before compiling. only_generate=True is
rejected outright (see Errors) — Device Builder ignores that field and
always runs a full build (ADR-0004 D4); it stays in the signature only
for input-shape compatibility.
Use when: building firmware before esphome_upload_device.
Not for: checking config validity only — use esphome_validate_config,
which is faster and skips package downloads.
Returns: {"device", "action": "compile", "exit_code", "success", "log_tail", "log_lines"}.
Errors: {"error": "esphome_unsupported_option", ...} for
only_generate=True (no I/O); {"error": "Invalid device name: ..."}
for a path-escaping or blocked (e.g. 'secrets') name; otherwise one of
esphome_dashboard.DashboardError's stable codes —
esphome_unreachable/esphome_auth_required add diagnosis (see
esphome_ping_dashboard); timeout adds log_tail/log_lines/
job_may_still_be_running (always True — do not retry, check
esphome_get_addon_logs); esphome_command_failed adds
dashboard_error_code/details.
Limits: blocks up to timeout seconds; log_lines truncates the log.
Inputs: name (required), timeout, log_lines, only_generate. Returns: object
esphome_get_addon_infoGet ESPHome add-on statusARead-onlyIdempotent
Get the ESPHome add-on's status, version and update availability via the Supervisor API.
The add-on slug is discovered dynamically from the live /addons list
(see _discover_esphome_slug) rather than guessed from a fixed set of
hashes — the hash prefix in <hash>_esphome differs per add-on-store
repository/installation.
Use when: checking whether the ESPHome add-on is installed, running,
and up to date.
Not for: log output — use esphome_get_addon_logs.
Returns: {"slug", "name", "state", "version", "version_latest", "update_available", "ingress_url"}.
Errors: {"error": "ESPHome add-on not found. Tried: [...]"} when no
matching add-on slug responds, or when SUPERVISOR_TOKEN is unset.
Inputs: no named parameters. Returns: object
esphome_get_addon_logsGet ESPHome add-on log outputARead-onlyIdempotent
Get the ESPHome add-on's recent log output.
Fetches raw text logs via the Supervisor API and returns the last
lines lines. Shows compile errors, OTA status and device connection
events. The add-on slug is discovered dynamically — see
esphome_get_addon_info.
Use when: diagnosing why esphome_compile_device/esphome_upload_device/
esphome_validate_config failed, or checking recent device activity.
Not for: any other add-on's logs — use
supervisor_get_addon_logs with its slug instead.
Returns: {"slug": ..., "logs": "<text>", "total_lines": <int>}.
Errors: {"error": "ESPHome add-on not found. Tried: [...]"} when no
matching slug responds; {"error": "HTTP <status>"} for a non-404 HTTP
error; {"error": str(e)} for any other failure.
Inputs: lines. Returns: object
esphome_get_configGet ESPHome device YAML configARead-onlyIdempotent
Read one ESPHome device's YAML config from /config/esphome/.
Resolves name to <name>.yaml under _ESPHOME_DIR, rejecting path
separators/leading dots/paths that escape that directory.
Use when: inspecting a device's current configuration before editing it
with esphome_write_config or one of the esphome_lvgl_* editors.
Not for: a device's HA entities — use esphome_get_device_entities.
Returns: {"name": <filename>, "content": <yaml text>}.
Errors: {"error": "Invalid device name: ..."} for a path-escaping
name; {"error": "Not found: ...", "esphome_dir": ...} when the file
doesn't exist.
Inputs: name (required). Returns: object
esphome_get_device_entitiesGet an ESPHome device's HA entitiesARead-onlyIdempotent
Get every HA entity belonging to one ESPHome device.
Slugifies device_name (lowercase, spaces/dashes to underscores) and, if
a device-registry entry's own slugified name matches, matches entities by
that device's device_id (precise: immune to one device's slug being a
substring of another's). Falls back to matching entity registry entries
whose platform is "esphome" and whose entity_id contains the slug
when no device-registry entry matches (or that lookup fails).
Use when: inspecting a specific device's exposed entities and their
current state.
Not for: the device list itself — use esphome_list_devices.
Returns: list of {"entity_id", "name", "domain", "state", "attributes", "disabled"} dicts.
Errors: [{"error": str(e)}] when reading the entity registry or
states raises.
Inputs: device_name (required). Returns: result
esphome_list_devicesList ESPHome devicesARead-onlyIdempotent
List ESPHome devices from YAML configs, the HA device registry and online status.
Combines <name>.yaml files under /config/esphome/ with matching HA
device-registry entries (identified via ESPHome config entries,
identifiers domain, or manufacturer as a fallback). A device's
connected status comes from its own entities' states (entity registry
device_id match): any entity in a state other than "unavailable"
means connected, since ESPHome entities share one per-config-entry
availability flag (homeassistant/components/esphome/entity.py) —
not from a binary_sensor.*_api_connection_status entity, which is not
guaranteed to exist.
Use when: getting an overview of every ESPHome device, whether or not it
currently has a matching HA device.
Not for: one device's entities — use esphome_get_device_entities.
Returns: {"yaml_configs": [...], "ha_devices": [...], "online": <int>, "offline": <int>}, where each ha_devices entry's connected is True,
False, or None (no known entities/states yet).
Errors: ha_devices becomes [{"error": str(e)}] if reading the HA
device registry raises; entity-registry/config-entry/state lookups are
silently skipped (treated as empty) on error instead of failing the
whole call.
Inputs: no named parameters. Returns: object
esphome_lvgl_add_widgetAdd an LVGL widget to a pageADestructive
Add an LVGL widget to a page on an ESPHome device and save the whole config.
Appends {widget_type: properties} to the page's widgets list, then
rewrites the entire device YAML file via yaml.dump — comments, blank
lines and YAML anchors/aliases elsewhere in the file are NOT preserved.
A <file>.bak copy of the previous content is written first so the
original formatting can be recovered manually. Lambda callbacks
(on_click, on_value_changed) are not supported here — add them
manually via esphome_get_config/esphome_write_config. Calling this
twice with the same arguments adds two separate widgets.
Use when: adding one widget to an existing LVGL page without
hand-editing the full YAML.
Not for: removing a widget — use esphome_lvgl_delete_widget; not for
lambda callbacks or other structural edits — use
esphome_get_config/esphome_write_config. After adding, run
esphome_lvgl_validate/esphome_validate_config, then
esphome_compile_device and esphome_upload_device to deploy.
Returns: {"success": True, "name": ..., "bytes": ..., "backup": ..., "added": <widget_type>, "to_page": <page_id>} on success.
Errors: {"error": "..."} when the file can't be found/parsed, when
there is no lvgl: section, when page_id doesn't exist, or when the
save itself fails ({"success": False, "error": ...}).
Limits: rewrites and overwrites the whole file; only the pre-write
content is recoverable, via the .bak copy.
Inputs: page_id (required), properties (required), device_name (required), widget_type (required). Returns: object
esphome_lvgl_delete_widgetDelete an LVGL widget from a pageADestructiveIdempotent
Delete an LVGL widget by id from a page on an ESPHome device and save the whole config.
Removes the matching widget from the page's widgets list, then
rewrites the entire device YAML file via yaml.dump — comments, blank
lines and YAML anchors/aliases elsewhere in the file are NOT preserved.
A <file>.bak copy of the previous content is written first so the
original formatting can be recovered manually.
Use when: removing one widget from an existing LVGL page.
Not for: adding a widget — use esphome_lvgl_add_widget. After
deleting, run esphome_lvgl_validate/esphome_validate_config, then
esphome_compile_device and esphome_upload_device to deploy.
Returns: {"success": True, "name": ..., "bytes": ..., "backup": ..., "deleted": <widget_id>, "from_page": <page_id>} on success.
Errors: {"error": "..."} when the file can't be found/parsed, when
there is no lvgl: section, when page_id/widget_id doesn't exist,
or when the save itself fails ({"success": False, "error": ...}).
Limits: rewrites and overwrites the whole file; only the pre-write
content is recoverable, via the .bak copy.
Inputs: page_id (required), widget_id (required), device_name (required). Returns: object
esphome_lvgl_get_pagesGet an ESPHome device's LVGL pagesARead-onlyIdempotent
Get the LVGL pages configured on an ESPHome device.
Parses the device's YAML and reads the lvgl: section's pages and
displays[0].default_page.
Use when: getting page IDs, background colors and widget counts before
drilling into one page with esphome_lvgl_get_page_widgets.
Not for: the widgets on one specific page — use
esphome_lvgl_get_page_widgets.
Returns: {"device": ..., "default_page": ..., "pages": [{"id", "bg_color", "widget_count"}, ...]}.
Errors: {"error": "..."} when the file can't be found/parsed, or when
there is no lvgl: section in the device config.
Inputs: device_name (required). Returns: object
esphome_lvgl_get_page_widgetsGet widgets on an ESPHome LVGL pageARead-onlyIdempotent
Get all LVGL widgets on one page of an ESPHome device.
Parses the device's YAML and summarises each widget on the requested
page: type, ID, position and key properties. Lambda callback values are
shown as the literal string <lambda> (opaque here — use
esphome_get_config to see the full source).
Use when: inspecting an existing page's widget tree before adding or
removing a widget.
Not for: page-level metadata only — use esphome_lvgl_get_pages.
Returns: {"device", "page", "widget_count", "widgets": [...]}.
Errors: {"error": "..."} when the file can't be found/parsed, when
there is no lvgl: section, or when page_id doesn't exist.
Inputs: page_id (required), device_name (required). Returns: object
esphome_lvgl_get_stylesGet an ESPHome device's LVGL stylesARead-onlyIdempotent
Get the LVGL theme and style definitions from an ESPHome device config.
Parses the device's YAML and reads the lvgl: section's theme,
style_definitions and gradients keys.
Use when: checking what theme/styles a device's LVGL UI currently uses
before referencing a style name in a new widget.
Not for: page/widget content — use esphome_lvgl_get_pages/
esphome_lvgl_get_page_widgets.
Returns: {"device", "theme", "style_definitions", "gradients"}.
Errors: {"error": "..."} when the file can't be found/parsed, or when
there is no lvgl: section in the device config.
Inputs: device_name (required). Returns: object
esphome_lvgl_list_devicesList ESPHome devices with LVGL supportARead-onlyIdempotent
List ESPHome devices whose YAML config has an lvgl: section.
Parses every device YAML under /config/esphome/ (tolerating parse
errors by skipping that device) and reports the ones with LVGL display
support.
Use when: finding which devices have an LVGL screen before inspecting
or editing its pages/widgets.
Not for: page detail on one device — use esphome_lvgl_get_pages.
Returns: list of {"device", "pages": <count>, "page_ids": [...]}.
Inputs: no named parameters. Returns: result
esphome_lvgl_validateValidate an ESPHome device's LVGL structureARead-onlyIdempotent
Validate an ESPHome device's LVGL structure client-side, without the dashboard.
Checks for duplicate page/widget IDs and default_page references that
don't exist among the parsed pages. This is a structural check only —
it does not validate widget properties or ESPHome component
correctness.
Use when: a quick local pre-check after editing LVGL pages/widgets,
before a full esphome_validate_config or esphome_compile_device.
Not for: full component/property validation — use
esphome_validate_config.
Returns: {"device", "valid": <bool>, "pages": <count>, "widgets": <count>, "issues": [...]}.
Errors: {"error": "...", "valid": False} when the file can't be
found/parsed, or when there is no lvgl: section in the device config.
Inputs: device_name (required). Returns: object
esphome_ping_dashboardCheck ESPHome dashboard reachabilityARead-onlyIdempotent
Check whether the ESPHome Device Builder dashboard responds.
Resolves where the dashboard is (esphome_dashboard.DashboardLocator,
ADR-0004 D2) — an explicit ESPHOME_DASHBOARD_URL (mode "explicit")
if set, else in add-on mode the installed ESPHome add-on's own
site-ingress port, always dialled at http://127.0.0.1:<ingress_port>
(mode "supervisor_ingress") — then calls GET /ping there. A False
reachable here does not necessarily mean the add-on itself is down;
see diagnosis/advice for what to check next.
Use when: diagnosing a connection failure from
esphome_compile_device/esphome_validate_config/esphome_upload_device,
or confirming the dashboard is reachable before calling one of them.
Not for: add-on version/update status — use esphome_get_addon_info.
Returns: {"reachable": True, "url": ..., "mode": "explicit"| "supervisor_ingress", "result": {...}} (the raw /ping JSON) on
success.
Errors: never raises. On failure: {"reachable": False, "error": <stable code>, "message": ...} — "esphome_not_configured" (neither
ESPHOME_DASHBOARD_URL nor the add-on's own info could be resolved) has
no url/mode; "esphome_unreachable"/"esphome_auth_required" add
url, mode and a diagnosis: {"mode", "dashboard_url", "slug", "addon_state", "ingress", "ingress_port", "advice"} built from the
ESPHome add-on's own GET /addons/<slug>/info (slug/addon_state/
ingress/ingress_port are None outside supervisor_ingress mode).
Inputs: no named parameters. Returns: object
esphome_upload_deviceFlash firmware to an ESPHome deviceADestructive
Flash previously compiled firmware to an ESPHome device via the dashboard's /upload WebSocket route.
Requires the device to already be built (esphome_compile_device) and,
for OTA, reachable with a matching OTA password. Without confirm=True
returns a confirmation prompt and performs no I/O (ADR-0004 D5) — this
overwrites the running firmware with no automatic rollback if broken.
Same "ESPHome Device Builder" (esphome/device-builder) spawn wire
protocol as esphome_compile_device, on /upload.
Use when: deploying a compiled build to the device, once confirmed.
Not for: building the firmware — use esphome_compile_device first.
Returns: {"device", "action": "upload", "exit_code", "success", "log_tail", "log_lines"} on completion.
Errors: {"error": "confirmation_required", "message", "action"} when
confirm is false (checked first, before name is resolved);
{"error": "Invalid device name: ..."} for a path-escaping or blocked
(e.g. 'secrets') name; otherwise one of
esphome_dashboard.DashboardError's stable codes —
esphome_unreachable/esphome_auth_required add diagnosis (see
esphome_ping_dashboard); timeout adds log_tail/log_lines/
job_may_still_be_running (always True — do not retry, check
esphome_get_addon_logs); esphome_command_failed adds
dashboard_error_code/details.
Limits: requires confirm=True; blocks up to timeout seconds; no
rollback if the upload succeeds but firmware is broken.
Inputs: name (required), port, confirm, timeout, +1 more. Returns: object
esphome_validate_configValidate ESPHome device configARead-onlyIdempotent
Validate an ESPHome device's YAML config without compiling it.
Uses the devices/validate command on Device Builder's newer
multiplexed /ws protocol (github.com/esphome/device-builder,
docs/API.md) — the legacy /validate route from the old ESPHome
dashboard no longer exists. Unlike esphome_compile_device, this never
builds firmware or fetches PlatformIO packages. If the dashboard needs
a username/password, this fails fast instead of hanging (no credential
wiring exists here).
Use when: checking a config's validity quickly, e.g. before
esphome_compile_device.
Not for: a full firmware build — use esphome_compile_device; not for
LVGL-only structural checks — use esphome_lvgl_validate, which runs
without the dashboard.
Returns: {"device", "action": "validate", "success", "result", "log_tail", "log_lines"}.
Errors: {"error": "Invalid device name: ..."} for a path-escaping or
blocked (e.g. 'secrets') name; otherwise one of
esphome_dashboard.DashboardError's stable codes —
esphome_auth_required (credentials this tool cannot supply) and
esphome_unreachable add diagnosis (see esphome_ping_dashboard);
timeout adds log_tail/log_lines/job_may_still_be_running
(always False — validation enqueues no job); esphome_command_failed
adds dashboard_error_code/details.
Inputs: name (required), timeout, log_lines. Returns: object
esphome_write_configWrite ESPHome device YAML configADestructiveIdempotent
Write a full ESPHome device YAML config to /config/esphome/, overwriting any existing file.
Validates YAML syntax first (HA custom tags !secret/!include/
!lambda/!extend/!remove pass through unchanged) and only writes if
that succeeds. This replaces the whole file — there is no merge with
the previous content and, unlike git_safe_write_with_checkpoint, no
checkpoint commit is made first, so the previous content is not
recoverable through this tool.
Use when: saving a complete device config you already have in full,
e.g. after fetching and editing it with esphome_get_config.
Not for: a git-checkpointed config write — use
git_safe_write_with_checkpoint; for a generic /config file write use
files_write_config_file; for a single LVGL widget edit use
esphome_lvgl_add_widget/esphome_lvgl_delete_widget instead of
hand-editing the whole YAML text.
Returns: {"success": True, "name": ..., "path": ..., "bytes": ...} on
success; a remote external_components:/packages: source
(github:///gitlab:///codeberg:///git:///http(s)://, or a dict
with a url) adds "warning" (review before esphome_compile_device,
which fetches and runs it) and "external_sources": [...]; a config
with none, or only local (type: local, bare-path, !include) ones,
gets neither key.
Errors: {"success": False, "error": "YAML validation failed: ..."} for
invalid YAML; {"success": False, "error": "Invalid device name: ..."}
for a path-escaping name.
Inputs: name (required), content (required). Returns: object
files_append_to_config_fileAppend to a config fileA
Append text to the end of an existing config file.
Resolves relative_path via _safe_path, reads its current text,
appends content after a newline, YAML-checks the combined text only
when validate_yaml=True and the extension is .yaml/.yml, then writes
the combined text back.
Use when: adding raw YAML/JSON/txt lines that already match the file's
existing list indentation.
Not for: automations — use automations_set_automation_config, which
edits by config id instead of a raw text append.
Returns: dict {"success": True, "path": ...} on success, or
{"success": False, "error": ...} when validate_yaml=True and the
combined text fails to parse.
Errors: raises FileNotFoundError when the file does not exist, and
raises PermissionError (from _safe_path) for a path outside the
config directory, a disallowed extension, or secrets.yaml/.storage.
Limits: validate_yaml defaults to False, so an invalid append is
written without warning unless explicitly checked.
Inputs: content (required), relative_path (required), validate_yaml. Returns: object
files_delete_config_fileDelete a config fileADestructiveIdempotent
Permanently delete one config file under /config after an explicit confirmation.
Without confirm=True returns a confirmation prompt and does not
resolve or touch relative_path at all. With confirm=True, resolves
relative_path via _safe_path and calls Path.unlink(); there is no
backup or trash in this tool — deletion is immediate and irreversible
from here alone.
Use when: removing a YAML/JSON/txt file that HA no longer needs, once
that removal is confirmed.
Not for: keeping the ability to undo — commit the config to git first
(git_git_commit_all) or write through
git_safe_write_with_checkpoint so a rollback stays possible.
Returns: dict {"success": True, "deleted": ...} when confirmed,
otherwise a confirmation prompt.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false; raises FileNotFoundError
when the file does not exist, and raises PermissionError (from
_safe_path) for a path outside the config directory, a disallowed
extension, or secrets.yaml/.storage.
Limits: requires confirm=True; the deletion runs immediately with no
undo once confirmed.
Inputs: relative_path (required), confirm. Returns: object
files_list_config_filesList config filesARead-onlyIdempotent
Recursively list config files with allowed extensions under /config.
Resolves subdirectory (default the config root) under HA_CONFIG_PATH,
recurses with Path.rglob('*'), and returns config-root-relative paths
for files whose extension is in .yaml/.yml/.json/.txt, skipping
secrets.yaml and .storage/.
Use when: discovering which config files exist before reading or
writing one.
Not for: reading a file's content once you have its path — use
files_read_config_file.
Returns: list[str] of config-root-relative file paths.
Limits: output can be large for the /config root; a subdirectory that
resolves (after following symlinks) outside /config returns an empty
list instead of listing files outside the config directory.
Inputs: subdirectory. Returns: result
files_read_config_fileRead a config fileARead-onlyIdempotent
Read one config file's raw text from the HA config directory.
Resolves relative_path under HA_CONFIG_PATH via _safe_path (blocking
paths outside the directory, disallowed extensions, and secrets.yaml/
.storage) and returns its content as a UTF-8 string; nothing is parsed
or validated.
Use when: reading the current text of a YAML/JSON/txt file before
editing it.
Not for: checking whether that text is valid YAML — pass it to
files_validate_yaml_content; discovering which files exist first —
use files_list_config_files.
Returns: str, the file's raw text (UTF-8).
Errors: raises FileNotFoundError when the file does not exist, and
raises PermissionError (from _safe_path) when relative_path
resolves outside the config directory, uses a disallowed extension, or
targets secrets.yaml/.storage.
Inputs: relative_path (required). Returns: result
files_validate_yaml_contentValidate YAML syntaxARead-onlyIdempotent
Check YAML syntax for a string without writing anything.
Parses content with a Home-Assistant-tolerant YAML loader that
accepts !include*/!secret/!env_var/!input as opaque values, and reports
only whether parsing succeeded and the top-level type.
Use when: checking a YAML snippet's syntax before calling
files_write_config_file or automations_set_automation_config.
Not for: full HA schema validation — use system_check_config; HA tags
here are accepted but not resolved, so only syntax is checked, not HA
schema validity.
Returns: dict {"valid": True, "type": ...} (top-level type name only,
not the parsed content) or {"valid": False, "error": ...}.
Errors: returns {"valid": False, "error": str(e)} for a YAML parse
error rather than raising.
Inputs: content (required). Returns: object
files_write_config_fileOverwrite a config fileADestructiveIdempotent
Overwrite or create one config file under /config with new content.
Resolves relative_path via _safe_path, YAML-checks content first
unless validate_yaml=False or the extension isn't .yaml/.yml, then
creates parent directories as needed and writes the file, replacing any
previous content at that path.
Use when: no rollback point for the previous content is needed.
Not for: keeping a rollback point — use git_safe_write_with_checkpoint,
which commits the pre-write state first; ESPHome device YAML — use
esphome_write_config.
Returns: dict {"success": True, "path": ...} on success, or
{"success": False, "error": ...} when validate_yaml catches invalid
YAML before writing.
Errors: raises PermissionError (from _safe_path) for a path outside
the config directory, a disallowed extension, or secrets.yaml/.storage;
returns {"success": False, "error": ...} instead of raising for
invalid YAML.
Limits: no backup is taken — the previous content is permanently lost.
Does not reload Home Assistant.
Inputs: content (required), relative_path (required), validate_yaml. Returns: object
git_git_checkout_branchSwitch config to an existing branchADestructiveIdempotent
Switch the HA config git repository to an existing branch.
Calls repo.git.checkout(branch_name), which replaces every tracked
file under /config with that branch's committed version — the live
configuration Home Assistant reads from changes as soon as this
returns.
Use when: switching between prepared configurations that are tracked
as branches.
Not for: creating a branch that does not exist yet — use
git_git_create_branch.
Returns: dict {"status": "switched", "branch": ...}.
Errors: raises an exception from gitpython when branch_name does not
exist, or when uncommitted local changes would conflict with the
target branch's files; raises RuntimeError (from _repo()) when no
git repo exists.
Limits: no confirm parameter; a conflicting uncommitted change blocks
the checkout rather than being silently discarded (plain git
behaviour), but a non-conflicting one carries over onto the new
branch.
Inputs: branch_name (required). Returns: object
git_git_commit_allCommit all config changesA
Stage and commit every change in the HA config directory.
Calls _repo(), stages everything with git add -A, and commits
message unless nothing is dirty, in which case no commit is made.
Use when: creating a checkpoint before a risky change to /config.
Not for: writing one file and checkpointing it in a single call — use
git_safe_write_with_checkpoint.
Returns: dict {"status": "committed", "sha", "message"}, or
{"status": "nothing_to_commit"} when the working tree is clean.
Errors: raises RuntimeError (from _repo()) when gitpython is not
installed or no git repo exists yet — run git_git_init_config first.
Inputs: message (required). Returns: object
git_git_create_branchCreate and switch to a new git branchA
Create a new git branch from the current commit and switch to it.
Calls repo.create_head(branch_name) then branch.checkout();
uncommitted changes carry over onto the new branch, and live /config
files now follow it.
Use when: starting an isolated set of changes without touching the
current branch's commit history.
Not for: switching to a branch that already exists — use
git_git_checkout_branch.
Returns: dict {"status": "created_and_checked_out", "branch": ...}.
Errors: raises an exception from gitpython when a branch named
branch_name already exists; raises RuntimeError (from _repo())
when no git repo exists.
Inputs: branch_name (required). Returns: object
git_git_diffShow config git diffARead-onlyIdempotent
Show unstaged changes, or one commit's stat summary.
Without sha, calls repo.git.diff() for the unified diff of unstaged
changes to tracked files in /config, excluding staged changes and
untracked new files (see git_git_status). With sha, calls git show --stat <sha> for the commit header and per-file changed-line counts,
not the actual patch.
Use when: reviewing what changed before committing, or summarising one
past commit.
Returns: str, the raw diff or stat text.
Errors: raises RuntimeError (from _repo()) when no git repo exists;
raises an exception from gitpython when sha does not resolve to a
commit.
Limits: output is raw, unformatted text and can be large for big diffs.
Inputs: sha. Returns: result
git_git_init_configInitialize the config git repositoryAIdempotent
Initialize a git repository in the HA config directory.
Creates a git repo at HA_CONFIG_PATH via git.Repo.init unless a .git/
directory already exists there, writes a default .gitignore
(secrets.yaml, .storage/, .db, home-assistant.log) when none exists,
and makes one initial commit adding that .gitignore.
Use when: preparing /config before using any other git_* tool or
git_safe_write_with_checkpoint for the first time.
Returns: dict {"status": "initialized"|"already_initialized", "path": ...}.
Inputs: no named parameters. Returns: object
git_git_list_branchesList config git branchesARead-onlyIdempotent
List all local branches in the HA config git repository.
Calls _repo() and returns every local branch name from
repo.branches.
Returns: list[str] of local branch names.
Errors: raises RuntimeError (from _repo()) when gitpython is not
installed or no git repo exists yet — run git_git_init_config first.
Inputs: no named parameters. Returns: result
git_git_logList config git commitsARead-onlyIdempotent
List recent commits in the HA config git repository.
Calls _repo() and returns up to limit commits from
repo.iter_commits, most recent first, with short SHA, message, author
name and ISO commit date.
Use when: reviewing recent config changes before a rollback or diff.
Returns: list[dict] {"sha", "message", "author", "date"}.
Errors: raises RuntimeError (from _repo()) when gitpython is not
installed or no git repo exists yet — run git_git_init_config first.
Limits: limit caps the number of commits returned; no further
pagination is offered.
Inputs: limit. Returns: result
git_git_rollback_fileRestore a config file from git historyADestructiveIdempotent
Restore one file to its state at a specific commit.
Refuses a relative_path that resolves outside /config
(_resolve_within_config) before running anything, and without
confirm=True returns a safety prompt instead of touching the file;
with confirm=True it calls repo.git.checkout(sha, '--', relative_path), replacing the file's on-disk content with the version
from sha and losing any uncommitted changes to that file.
Use when: undoing an accidental edit to a single file.
Not for: resetting the whole config tree — use
git_git_rollback_to_commit.
Returns: dict {"status": "restored", "file", "to"} on success.
Errors: returns {"error": "invalid_path"|"path_outside_config", ...}
when relative_path escapes /config; returns {"error": "confirmation_required", ...} when confirm is not True; raises
RuntimeError (from _repo()) when no git repo exists.
Limits: requires confirm=True; uncommitted changes to the target
file are permanently lost once it runs.
Inputs: relative_path (required), sha, confirm. Returns: object
git_git_rollback_to_commitHard-reset config to a commitADestructiveIdempotent
Hard-reset the entire HA config directory to a previous commit.
Without confirm=True returns a safety prompt naming the current head commit;
with confirm=True calls repo.git.reset('--hard', sha), which
discards every commit and uncommitted change made after sha.
Use when: reverting /config entirely after a bad batch of changes, and
the target commit is already known.
Not for: restoring a single file — use git_git_rollback_file.
Returns: dict {"status": "reset", "to": sha} on success.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is not True; raises RuntimeError (from
_repo()) when no git repo exists.
Limits: requires confirm=True. WARNING: every commit and uncommitted
change made after sha is permanently and irreversibly lost.
Inputs: sha (required), confirm. Returns: object
git_git_statusShow config git statusARead-onlyIdempotent
Show git status of the HA config directory.
Calls _repo() for the /config git repo and returns the active branch,
staged/modified/untracked file lists (repo.index.diff,
repo.untracked_files) and an overall dirty flag.
Use when: checking what changed in /config before committing or
writing a file.
Returns: dict {"branch", "staged", "modified", "untracked", "is_dirty"}.
Errors: raises RuntimeError (from _repo()) when gitpython is not
installed or no git repo exists yet at HA_CONFIG_PATH — run
git_git_init_config first.
Inputs: no named parameters. Returns: object
git_safe_write_with_checkpointWrite a config file with a git checkpointAIdempotent
Write one config file after committing a checkpoint of the prior state.
Stages and commits every uncommitted change under /config as a
checkpoint commit (only when the tree is dirty), then calls the same
write_config_file logic files_write_config_file uses for
relative_path/content, and finally stages and commits that change
with commit_message (or a default message) if the write succeeded.
Use when: overwriting a config file while keeping a git-based rollback
point, unlike a plain overwrite.
Not for: a write without a checkpoint — use
files_write_config_file; ESPHome device YAML — use
esphome_write_config.
Returns: dict — the underlying write result ({"success": True, "path": ...} or {"success": False, "error": ...}), plus git_sha/
git_message when the new-content commit was made.
Errors: raises RuntimeError (from _repo()) when no git repo exists
— run git_git_init_config first; returns {"success": False, "error": ...} unchanged when YAML validation fails, in which case the
checkpoint commit of the prior dirty state (if any) still happened, but
no new-content commit is made.
Limits: does not reload Home Assistant; same file-extension and
location limits as files_write_config_file.
Inputs: content (required), relative_path (required), commit_message. Returns: object
hacs_add_custom_repositoryAdd a custom HACS repositoryAIdempotent
Register a custom repository with HACS / the Marketplace so it becomes installable.
Calls marketplace/repositories/add on HA 2026.11+ or
hacs/repositories/add on older HA, with url as its repository
field and category. This only registers the repository — it does not
install it.
Use when: a repository is not in the default store and needs adding
before it can be installed.
Not for: installing an already-registered repository — use
hacs_install_hacs_repository.
Returns: {"status": "ok", "backend": "marketplace"|"hacs"}, or an
error dict.
Errors: {"error", "code", "backend", "hint"} when url/category is
invalid or the command fails; the Marketplace needs the first-run
warning accepted (warning_not_accepted) and a connected GitHub account
(github_not_connected), both in Settings -> Marketplace (as an add-on
see hint);
unknown_command when neither backend is available.
Inputs: url (required), category (required). Returns: result
hacs_get_hacs_repositoryGet HACS repository detailsARead-onlyIdempotent
Get details about a single HACS / Marketplace repository.
Calls marketplace/repository/info on HA 2026.11+ or
hacs/repository/info on older HA, passing repo_id as the
repository_id field.
Use when: checking one repository's installed/available version or
metadata before installing or updating it.
Not for: browsing many repositories at once — use
hacs_list_hacs_repositories.
Returns: HA's raw repository-info dict, or an error dict.
Errors: {"error", "code", "backend", "hint"} when repo_id is unknown
(repository_not_found) or the command fails; code unknown_command
when neither the Marketplace nor HACS is available.
Inputs: repo_id (required). Returns: result
hacs_install_hacs_repositoryInstall a HACS repositoryAIdempotent
Install a HACS / Marketplace repository, optionally pinning a version.
Calls marketplace/repository/install on HA 2026.11+ or
hacs/repository/download on older HA (installs, or re-downloads in
place when already installed). Fetches the release from its source
(typically GitHub) — an outbound fetch beyond this HA instance.
Use when: adding an integration/plugin/theme that is already known (via
the default store or hacs_add_custom_repository).
Not for: a repository not known yet — use hacs_add_custom_repository
first.
Returns: {"status": "ok", "backend": "marketplace"|"hacs"}, or an
error dict.
Errors: {"error", "code", "backend", "hint"}; on the Marketplace
warning_not_accepted until the first-run warning is accepted in
Settings -> Marketplace (nexus never accepts it; as an add-on see
hint), replaces_built_in
for a repository that replaces a built-in integration (install it from
the UI), github_rate_limited; unknown_command when neither backend
is available; code null on a timeout (check with
hacs_get_hacs_repository before retrying).
Limits: waits up to 120 s for HA's answer (an MCP client with a shorter
timeout may give up first — then check with hacs_get_hacs_repository
before retrying); most categories need a restart of the component.
Inputs: repo_id (required), version. Returns: result
hacs_list_hacs_critical_updatesList HACS pending upgradesARead-onlyIdempotent
List installed HACS / Marketplace repositories that have a pending upgrade available.
Calls the same list command as hacs_list_hacs_repositories
(marketplace/repositories/list on HA 2026.11+,
hacs/repositories/list on older HA) and keeps entries whose
pending_upgrade flag is set, despite this tool's name — there is no
separate "critical" severity here.
Use when: finding what needs hacs_update_hacs_repository without
filtering the full list manually.
Not for: every repository regardless of upgrade state — use
hacs_list_hacs_repositories.
Returns: list of repository dicts with pending_upgrade truthy, or an
error dict.
Errors: {"error", "code", "backend", "hint"} when the command fails;
{"error": "Unexpected response shape", "raw": result} when it does not
return a list.
Inputs: no named parameters. Returns: result
hacs_list_hacs_repositoriesList HACS repositoriesARead-onlyIdempotent
List the HACS / Marketplace repositories known to this Home Assistant instance.
On HA 2026.11+ calls the built-in Marketplace's
marketplace/repositories/list; on older HA falls back to HACS's
hacs/repositories/list. Optionally scoped to one category.
Use when: browsing or checking the state of repositories already known
(installed or not); id from here is the repo_id other tools take.
Not for: repositories not added yet — use hacs_add_custom_repository
first.
Returns: list of repository dicts as reported by HA (id, full_name,
category, installed, installed_version, available_version,
pending_upgrade, ...), or an error dict.
Errors: {"error", "code", "backend", "hint"} when the command fails;
code unknown_command with a hint when neither the Marketplace nor
HACS is available.
Inputs: category. Returns: result
hacs_uninstall_hacs_repositoryUninstall a HACS repositoryADestructiveIdempotent
Uninstall a HACS / Marketplace repository.
Calls marketplace/repository/uninstall on HA 2026.11+ or
hacs/repository/remove on older HA, which removes the installed files
for repo_id; the integration/plugin/theme stops working until
reinstalled.
Use when: removing a component that is no longer needed.
Not for: only skipping an update while keeping it installed — there is
no such option exposed here.
Returns: {"status": "ok", "backend": "marketplace"|"hacs"}, or an
error dict.
Errors: {"error", "code", "backend", "hint"} when repo_id is not
installed or the command fails; the Marketplace refuses an integration
that still has config entries (repository_in_use — delete them first);
unknown_command when neither backend is available.
Limits: waits up to 120 s (with GitHub connected the Marketplace first
re-fetches the repository); an MCP client with a shorter timeout may give
up first — then check with hacs_get_hacs_repository before retrying.
Inputs: repo_id (required). Returns: result
hacs_update_hacs_repositoryUpdate a HACS repositoryADestructive
Update an installed HACS / Marketplace repository to its latest available version.
Neither backend has a single update command. Runs repository/refresh
(re-fetch), repository/info (read available_version), then installs
that version (marketplace/repository/install on HA 2026.11+,
hacs/repository/download on older HA). The previous version is only
recoverable from a backup taken beforehand.
Use when: pending_upgrade is set (see hacs_list_hacs_critical_updates)
and the new version should be applied.
Not for: pinning a specific version — use hacs_install_hacs_repository
with version set.
Returns: {"status": "ok", "backend": "marketplace"|"hacs"}, or an
error dict.
Errors: {"error", "code", "backend", "hint"} from the first failing
call (later calls are not made); on the Marketplace
warning_not_accepted until the first-run warning is accepted in
Settings -> Marketplace (as an add-on see hint); {"error": "No available_version reported for this repository", "raw": ...} when info has nothing to update to;
code null on a timeout (check with hacs_get_hacs_repository before
retrying).
Limits: downloads over the network; the install step waits up to 120 s
(an MCP client with a shorter timeout may give up first — then check with
hacs_get_hacs_repository); no automatic rollback.
Inputs: repo_id (required). Returns: result
helpers_cancel_timerCancel a timer helperAIdempotent
Cancel a running timer helper.
Calls timer.cancel with {"entity_id": entity_id} over HTTP.
Use when: stopping a timer before it finishes.
Not for: starting one — use helpers_start_timer.
Returns: the list of states changed by the call.
Inputs: entity_id (required). Returns: result
helpers_increment_counterIncrement a counter helperA
Increment a counter helper by its configured step.
Calls counter.increment with {"entity_id": entity_id} over HTTP;
repeating this call keeps increasing the counter's value.
Use when: counting up an event occurrence.
Not for: setting the counter back to zero — use
helpers_reset_counter.
Returns: the list of states changed by the call.
Inputs: entity_id (required). Returns: result
helpers_list_helpersList helper entitiesARead-onlyIdempotent
List every helper entity across all helper domains, with its current state.
Reads all states via ha.get_states() over HTTP and keeps only entities
whose domain is one of input_boolean, input_number, input_text,
input_select, input_datetime, input_button, counter, timer, schedule.
Use when: browsing which helpers exist and their current values.
Not for: helpers of one specific domain filtered generically — use
entities_list_entities with domain set.
Returns: list of dicts with entity_id, state, attributes for each
matching helper entity.
Inputs: no named parameters. Returns: result
helpers_reload_helpersReload helper entities from configAIdempotent
Reload every helper domain's entities from configuration in one call.
Calls <domain>.reload over HTTP for each of input_boolean,
input_number, input_text, input_select, input_datetime, counter, timer
in turn; a domain whose reload call raises is skipped but its error is
captured rather than silently dropped.
Use when: applying YAML changes across several helper domains without
restarting Home Assistant.
Not for: reloading one specific domain — use services_reload_config.
Returns: {"reloaded": [...], "failed": {domain: message}} — combined
list of states changed across every domain that reloaded successfully,
plus a per-domain map of the error message for every domain whose
reload call raised.
Errors: a domain's failure never raises out of this call; instead its
exception message is recorded under failed[<domain>] so the caller can
tell which domain, if any, did not reload.
Inputs: no named parameters. Returns: object
helpers_reset_counterReset a counter helperAIdempotent
Reset a counter helper's value back to 0.
Calls counter.reset with {"entity_id": entity_id} over HTTP; the
counter is runtime UI state, not stored configuration.
Use when: clearing a counter back to its initial value.
Not for: increasing it by one — use helpers_increment_counter.
Returns: the list of states changed by the call.
Inputs: entity_id (required). Returns: result
helpers_set_input_booleanSet an input_boolean valueAIdempotent
Set an input_boolean helper to true or false.
Calls input_boolean.turn_on when value is true, otherwise
input_boolean.turn_off, over HTTP.
Use when: setting a known boolean helper to a specific value.
Not for: any other domain's on/off state — use entities_turn_on/
entities_turn_off, which work generically across domains including
input_boolean.
Returns: the list of states changed by the call.
Inputs: value (required), entity_id (required). Returns: result
helpers_set_input_datetimeSet an input_datetime valueAIdempotent
Set an input_datetime helper's date, time or combined datetime value.
Calls input_datetime.set_datetime over HTTP with whichever of date,
time, datetime are given; passing none of them still calls the
service with only entity_id.
Use when: writing a specific date/time to an input_datetime helper. Returns: the list of states changed by the call.
Inputs: entity_id (required), date, time, datetime. Returns: result
helpers_set_input_numberSet an input_number valueAIdempotent
Set an input_number helper's numeric value.
Calls input_number.set_value with {"entity_id": entity_id, "value": value} over HTTP.
Use when: writing a specific number to an input_number helper.
Not for: a number/climate entity too — entities_set_value covers
input_number identically plus the number and climate domains.
Returns: the list of states changed by the call.
Inputs: value (required), entity_id (required). Returns: result
helpers_set_input_selectSelect an input_select optionAIdempotent
Set an input_select helper to one of its configured options.
Calls input_select.select_option with {"entity_id": entity_id, "option": option} over HTTP.
Use when: setting a known input_select helper to a specific option.
Not for: the generic select/input_select dispatch that also handles
plain select entities — entities_select_option covers input_select
identically plus the select domain.
Returns: the list of states changed by the call.
Inputs: option (required), entity_id (required). Returns: result
helpers_set_input_textSet an input_text valueAIdempotent
Set an input_text helper's text value.
Calls input_text.set_value with {"entity_id": entity_id, "value": value} over HTTP.
Use when: writing a specific string to an input_text helper. Returns: the list of states changed by the call.
Inputs: value (required), entity_id (required). Returns: result
helpers_start_timerStart a timer helperAIdempotent
Start a timer helper, optionally overriding its duration.
Calls timer.start over HTTP with entity_id and duration when
given; calling this on an already-running timer restarts it with the
new duration.
Use when: starting a countdown, e.g. for a reminder or process timeout.
Not for: stopping it early — use helpers_cancel_timer.
Returns: the list of states changed by the call.
Inputs: entity_id (required), duration. Returns: result
history_get_error_logGet HA error logARead-onlyIdempotent
Fetch Home Assistant's error log as plain text.
Prefers the raw log file via GET /api/error_log. That view only
exists when HA logs to a file — Supervisor installs ship with
duplicate_log_file: false, so it 404s there, in which case the
warning/error records held by the system_log integration are rendered
into log-file-like text instead.
Use when: diagnosing recent warnings/errors across the whole instance.
Not for: one entity's history or logbook — use
history_get_state_history or history_get_logbook.
Returns: plain-text log content, from either source.
Errors: re-raises httpx.HTTPStatusError for any status other than 404
from /api/error_log.
Inputs: no named parameters. Returns: result
history_get_ha_configGet HA configurationARead-onlyIdempotent
Get Home Assistant's current configuration.
Calls GET /api/config for location, unit system, HA version and
loaded components.
Use when: version, location, unit system or the loaded-components list
is needed.
Not for: the equivalent WebSocket command — use ws_get_config; for
subsystem health checks — use system_get_system_health.
Returns: HA's raw config payload (latitude, longitude,
unit_system, version, components, and related fields).
Errors: raises httpx.HTTPStatusError if the HA API request fails.
Inputs: no named parameters. Returns: object
history_get_logbookGet logbook entriesARead-onlyIdempotent
Get human-readable logbook entries from the last N hours.
Calls GET /api/logbook/<start>, optionally filtered by entity_id,
where start is now - hours.
Use when: a narrative of what happened (state changes, triggered
automations) is more useful than raw state-history records.
Not for: raw per-state timestamps and values for one entity — use
history_get_state_history.
Returns: HA's raw logbook payload — a list of {when, name, message, entity_id, ...}-shaped entries.
Errors: raises httpx.HTTPStatusError if the HA API request fails.
Limits: only as far back as the recorder integration has retained
logbook data.
Inputs: hours, entity_id. Returns: result
history_get_state_historyGet entity state historyARead-onlyIdempotent
Get an entity's recorded state history over the last N hours.
Calls GET /api/history/period/<start> filtered to entity_id, where
start is now - hours; returns whatever the recorder database has
kept for that window.
Use when: seeing how one entity's state changed over time, e.g. a
temperature trend.
Not for: human-readable event descriptions — use
history_get_logbook; this is raw, short-term state history, not the
recorder's long-term pre-aggregated sum/mean/min/max values — use
statistics_get_statistics for those, or statistics_list_statistic_ids
to discover which entities have them.
Returns: HA's raw history-period payload — a list of state-change
records for the entity.
Errors: raises httpx.HTTPStatusError if the HA API request fails.
Limits: only as far back as the recorder integration has retained data
for this entity.
Inputs: entity_id (required), hours. Returns: result
history_get_system_infoCheck API livenessARead-onlyIdempotent
Get Home Assistant's raw API liveness message.
Calls GET /api/, which returns only a fixed liveness message (e.g.
{"message": "API running."}) — no version or system data despite the
tool's name.
Use when: a plain proof that the HTTP API is answering is enough.
Not for: version/location/units/components — use
history_get_ha_config; for subsystem health — use
system_get_system_health; for Core/OS details — use
supervisor_get_core_info or supervisor_get_host_info; for a simple
reachable/unreachable boolean — use system_ping_ha.
Returns: {"message": "API running."} (HA's fixed liveness payload).
Errors: raises httpx.HTTPStatusError if the HA API request fails.
Inputs: no named parameters. Returns: object
integrations_abort_config_flowAbort a config flowAIdempotent
Abort a config flow that has not been finished yet.
Calls DELETE /api/config/config_entries/flow/{flow_id}. Nothing was
persisted by an unfinished flow, so this discards only the flow's
in-progress state, not a config entry.
Use when: cancelling a setup that was started by mistake or is no
longer wanted.
Not for: removing a completed integration — use
integrations_remove_integration.
Returns: HA's abort response for the flow.
Errors: raises httpx.HTTPStatusError if flow_id is unknown or
already finished.
Inputs: flow_id (required). Returns: object
integrations_abort_options_flowAbort an options flowAIdempotent
Abort an options flow that has not been finished yet.
Calls DELETE /api/config/config_entries/options/flow/{flow_id}. The
entry's existing options are untouched, since nothing was applied by an
unfinished flow.
Use when: cancelling an options edit started by mistake or no longer
wanted.
Not for: cancelling a new-integration setup flow instead — use
integrations_abort_config_flow.
Returns: HA's abort response for the flow.
Errors: raises httpx.HTTPStatusError if flow_id is unknown or
already finished.
Inputs: flow_id (required). Returns: object
integrations_disable_integrationDisable a config entryAIdempotent
Disable an integration's config entry without removing it.
Calls the config_entries/disable WebSocket command with
disabled_by="user". The entry and its devices/entities stay
registered but stop loading until re-enabled.
Use when: pausing an integration temporarily while keeping its
configuration and registry entries intact.
Not for: permanently deleting the entry — use
integrations_remove_integration; to bring it back — use
integrations_enable_integration.
Returns: the config_entries/disable result.
Errors: raises RuntimeError if the underlying WebSocket call fails
(e.g. entry_id unknown).
Inputs: entry_id (required). Returns: object
integrations_enable_integrationEnable a config entryAIdempotent
Re-enable a previously disabled integration's config entry.
Calls the config_entries/disable WebSocket command with
disabled_by=None, which HA treats as clearing the disabled state.
Use when: bringing back an integration disabled via
integrations_disable_integration.
Not for: setting up a brand-new integration — use
integrations_start_config_flow.
Returns: the config_entries/disable result.
Errors: raises RuntimeError if the underlying WebSocket call fails
(e.g. entry_id unknown).
Inputs: entry_id (required). Returns: object
integrations_get_config_flowGet config flow stateARead-onlyIdempotent
Get the current state of a config flow without advancing it.
Calls GET /api/config/config_entries/flow/{flow_id}.
Use when: checking a flow's current step/schema again, e.g. after
losing the earlier response.
Not for: providing the step's answers — use
integrations_submit_config_flow_step.
Returns: the flow's current step payload, same shape as
integrations_start_config_flow's result.
Errors: raises httpx.HTTPStatusError if flow_id is unknown or
expired.
Inputs: flow_id (required). Returns: object
integrations_list_flow_handlersList installable integration domainsARead-onlyIdempotent
List every integration domain that supports a config flow.
Calls GET /api/config/config_entries/flow_handlers over HTTP for the
domains HA can set up through the UI-style flow (as opposed to
YAML-only integrations).
Use when: checking whether a domain can be installed via
integrations_start_config_flow before attempting it.
Not for: domains already configured — use system_list_integrations.
Returns: list of domain strings, e.g. ["shelly", "hue", ...].
Errors: raises httpx.HTTPStatusError if the HA API request fails.
Inputs: no named parameters. Returns: result
integrations_list_flows_in_progressList in-progress config flowsARead-onlyIdempotent
List config flows that were started but not yet finished.
Calls the config_entries/flow/progress WebSocket command.
Use when: finding a flow_id left over from an earlier
integrations_start_config_flow call, e.g. one waiting on discovery.
Not for: flows already completed into a config entry — use
system_list_integrations.
Returns: list of in-progress flow dicts (flow_id, handler,
step_id, context, and related fields).
Errors: raises RuntimeError if the underlying WebSocket call fails
(e.g. auth or WS-level error).
Inputs: no named parameters. Returns: result
integrations_remove_integrationRemove a config entryADestructiveIdempotent
Remove (uninstall) an integration's config entry after an explicit confirmation.
Calls DELETE /api/config/config_entries/entry/{entry_id} — there is no
config_entries/remove WebSocket command. HA unloads the integration
and deletes its entry; any devices/entities it owned typically go with
it. Without confirm=True nothing is removed.
Use when: an integration is no longer wanted and should be fully
uninstalled, not just disabled.
Not for: keeping the entry but pausing it — use
integrations_disable_integration.
Returns: HA's removal result when confirmed, otherwise a confirmation
prompt.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false; raises
httpx.HTTPStatusError if entry_id does not exist.
Limits: requires confirm=True; deletes the entry and its
devices/entities with no separate backup step.
Inputs: entry_id (required), confirm. Returns: object
integrations_start_config_flowStart an integration config flowA
Start a new config flow for an integration domain.
Calls POST /api/config/config_entries/flow with {"handler": handler, "show_advanced_options": show_advanced_options}; HA has no
WebSocket command for this. Each call creates a new, distinct flow.
Use when: beginning to set up a new integration through the same
step-by-step flow the HA UI uses.
Not for: editing an already-configured entry — use
integrations_start_options_flow.
Returns: the first step: {flow_id, step_id, data_schema, errors, ...}. Pass flow_id into integrations_submit_config_flow_step with
the user's answers.
Errors: raises httpx.HTTPStatusError if handler is not a valid
flow-handler domain.
Inputs: handler (required), show_advanced_options. Returns: object
integrations_start_options_flowStart an options flowA
Start the options flow for an existing config entry.
Calls POST /api/config/config_entries/options/flow, passing
entry_id as handler — HA's options-flow API reuses the config-flow
request shape and documents handler as "the entry_id" in this
context. Each call creates a new, distinct flow.
Use when: changing an already-configured integration's settings through
its own options UI/schema.
Not for: configuring a brand-new integration — use
integrations_start_config_flow.
Returns: the first step: {flow_id, step_id, data_schema, errors, ...}. Pass flow_id into integrations_submit_options_flow_step.
Errors: raises httpx.HTTPStatusError if entry_id does not exist or
the integration has no options flow.
Inputs: entry_id (required), show_advanced_options. Returns: object
integrations_submit_config_flow_stepSubmit a config flow stepADestructive
Submit user input for the current step of a config flow.
Calls POST /api/config/config_entries/flow/{flow_id} with
user_input. What this does depends entirely on the integration domain
driving the flow: it may just advance to the next form, or it may
validate credentials against the integration's own device/cloud service
and create or overwrite a real config entry that HA loads. HA does not
signal in advance which step is the last one, so any submitted step —
not only a visibly "final" one — can be the one that creates the entry.
Use when: providing the values a config-flow step asked for.
Not for: reading the current step without submitting anything — use
integrations_get_config_flow; cancelling a flow before it finishes —
use integrations_abort_config_flow.
Returns: the next step (form), a step with errors, or the finished
config entry. The returned step's last_step field is True only
when the integration explicitly declares this is the final step, and
None otherwise — most integrations leave it None even on their
actual last step, so None does not mean more steps remain.
Errors: raises httpx.HTTPStatusError if flow_id is unknown or
expired.
Limits: the integration handling this domain may reach an external
device or cloud service while validating user_input; a config entry
can be created without warning on any step.
Inputs: flow_id (required), user_input (required). Returns: object
integrations_submit_options_flow_stepSubmit an options flow stepADestructive
Submit a step of an options flow.
Calls POST /api/config/config_entries/options/flow/{flow_id} with
user_input. What this does depends entirely on the integration
domain: an intermediate step just advances the form, while the step
that finishes the flow applies the new options to the existing config
entry, replacing its previous options. HA does not signal in advance
which step is the last one, so any submitted step — not only a
visibly "final" one — can be the one that overwrites the options.
Use when: providing the values an options-flow step asked for.
Not for: reading the current step without submitting — there is no
separate "get options flow" tool; call
integrations_start_options_flow again to restart it; cancelling a
flow before it finishes — use integrations_abort_options_flow.
Returns: the next step (form), a step with errors, or the entry's
updated result. The returned step's last_step field is True only
when the integration explicitly declares this is the final step, and
None otherwise — most integrations leave it None even on their
actual last step, so None does not mean more steps remain.
Errors: raises httpx.HTTPStatusError if flow_id is unknown or
expired.
Limits: any submitted step, not only a visibly "final" one, may
overwrite the entry's previous options; the integration may reach an
external device or cloud service while validating the submitted
values.
Inputs: flow_id (required), user_input (required). Returns: object
integrations_update_integration_entryUpdate config entry propertiesADestructiveIdempotent
Update selected properties of an existing config entry.
Calls the config_entries/update WebSocket command with only the
fields given here (title, pref_disable_new_entities,
pref_disable_polling) — omitted fields keep their previous stored
value, but any field that is given replaces the previous one, which is
then lost.
Use when: renaming an integration's entry or changing its
entity-discovery/polling preferences without going through its options
flow.
Not for: settings specific to the integration itself (its actual
options schema) — use integrations_start_options_flow.
Returns: the config_entries/update result.
Errors: raises RuntimeError if the underlying WebSocket call fails
(e.g. entry_id unknown).
Inputs: entry_id (required), title, pref_disable_polling, pref_disable_new_entities. Returns: object
labels_assign_label_to_deviceAssign label to deviceAIdempotent
Assign a label to a device, keeping its existing labels.
Reads the device's current labels list from the device registry,
appends label_id if not already present, and writes the full list
back via WS config/device_registry/update.
Use when: tagging one device with a label without disturbing labels
already on it.
Not for: removing a label — use labels_remove_label_from_device.
Returns: dict with device_id, the resulting labels list, the raw WS
result, and ok.
Errors: on a WS failure, returns {"device_id": ..., "label_id": ..., "ok": false, "error": "<message>"}.
Inputs: label_id (required), device_id (required). Returns: object
labels_assign_label_to_entityAssign label to entityAIdempotent
Assign a label to an entity, keeping its existing labels.
Reads the entity's current labels list from the entity registry,
appends label_id if not already present, and writes the full list
back via WS config/entity_registry/update.
Use when: tagging one entity with a label without disturbing labels
already on it.
Not for: removing a label — use labels_remove_label_from_entity.
Returns: dict with entity_id, the resulting labels list, the raw WS
result, and ok.
Errors: on a WS failure, returns {"entity_id": ..., "label_id": ..., "ok": false, "error": "<message>"}.
Inputs: label_id (required), entity_id (required). Returns: object
labels_create_categoryCreate categoryA
Create a category within a registry scope.
Calls WS config/category_registry/create with scope and name,
plus icon if given; Home Assistant assigns a new category_id, so
calling this twice with the same name creates two separate categories.
Use when: you need a new category to group items within one scope, e.g.
automations.
Returns: the created category registry dict.
Errors: on a WS failure, returns {"error": "<message>"} instead of
raising.
Inputs: name (required), scope (required), icon. Returns: object
labels_create_labelCreate labelA
Create a new label.
Calls WS config/label_registry/create with name and any of icon,
color and description you pass; Home Assistant assigns a new
label_id, so calling this twice with the same name creates two separate
labels.
Use when: you need a new label to tag entities or devices with.
Returns: the created label registry dict (label_id, name, icon, color,
description).
Errors: on a WS failure, returns {"error": "<message>"} instead of
raising.
Inputs: name (required), icon, color, description. Returns: object
labels_delete_categoryDelete categoryADestructiveIdempotent
Delete a category from a registry scope.
Calls WS config/category_registry/delete with scope and
category_id and returns Home Assistant's result unchanged.
Use when: a category is no longer needed within its scope.
Returns: dict with scope, category_id, the raw WS result, and
ok.
Errors: on a WS failure, returns {"scope": ..., "category_id": ..., "ok": false, "error": "<message>"}.
Inputs: scope (required), category_id (required). Returns: object
labels_delete_labelDelete labelADestructiveIdempotent
Delete a label from the label registry.
Calls WS config/label_registry/delete with the given label_id and
returns Home Assistant's result unchanged.
Use when: a label is no longer needed.
Returns: dict with label_id, the raw WS result, and ok (true on
success).
Errors: on a WS failure, returns {"label_id": ..., "ok": false, "error": "<message>"} instead of raising.
Inputs: label_id (required). Returns: object
labels_list_categoriesList categoriesARead-onlyIdempotent
List categories defined for a given registry scope.
Calls WS config/category_registry/list with scope and returns the
result unfiltered; returns an empty list if the WS response is not a
list.
Use when: you need category IDs for one scope, e.g. before tagging
automations.
Returns: list of category registry dicts (category_id, name, icon) for
the given scope.
Errors: on a WS failure, returns [{"error": "<message>"}] instead of
raising.
Inputs: scope. Returns: result
labels_list_devices_with_labelList devices with labelARead-onlyIdempotent
List devices that currently have a given label assigned.
Reads the device registry over WebSocket and keeps rows whose labels
list contains label_id.
Use when: finding everything tagged with one label, e.g. before a bulk
action.
Returns: list of device registry dicts that have the label.
Errors: on a WS failure, returns [{"error": "<message>"}] instead of
raising.
Inputs: label_id (required). Returns: result
labels_list_entities_with_labelList entities with labelARead-onlyIdempotent
List entities that currently have a given label assigned.
Reads the entity registry over WebSocket and keeps rows whose labels
list contains label_id.
Use when: finding everything tagged with one label, e.g. before a bulk
action.
Returns: list of entity registry dicts that have the label.
Errors: on a WS failure, returns [{"error": "<message>"}] instead of
raising.
Inputs: label_id (required). Returns: result
labels_list_labelsList labelsARead-onlyIdempotent
List all labels defined in Home Assistant.
Calls WS config/label_registry/list and returns the result unfiltered;
returns an empty list if the WS response is not a list.
Use when: you need label IDs and names before filtering or assigning
them to entities or devices.
Returns: list of label registry dicts (label_id, name, icon, color,
description).
Errors: on a WS failure, returns [{"error": "<message>"}] instead of
raising.
Inputs: no named parameters. Returns: result
labels_remove_label_from_deviceRemove label from deviceAIdempotent
Remove a label from a device, keeping its other labels.
Reads the device's current labels list from the device registry,
drops label_id if present, and writes the remaining list back via WS
config/device_registry/update.
Use when: untagging one device from a label without touching its other
labels.
Not for: deleting the label itself everywhere — use
labels_delete_label.
Returns: dict with device_id, the resulting labels list, the raw WS
result, and ok.
Errors: on a WS failure, returns {"device_id": ..., "label_id": ..., "ok": false, "error": "<message>"}.
Inputs: label_id (required), device_id (required). Returns: object
labels_remove_label_from_entityRemove label from entityAIdempotent
Remove a label from an entity, keeping its other labels.
Reads the entity's current labels list from the entity registry,
drops label_id if present, and writes the remaining list back via WS
config/entity_registry/update.
Use when: untagging one entity from a label without touching its other
labels.
Not for: deleting the label itself everywhere — use
labels_delete_label.
Returns: dict with entity_id, the resulting labels list, the raw WS
result, and ok.
Errors: on a WS failure, returns {"entity_id": ..., "label_id": ..., "ok": false, "error": "<message>"}.
Inputs: label_id (required), entity_id (required). Returns: object
labels_update_categoryUpdate categoryADestructive
Update fields on an existing category.
Calls WS config/category_registry/update; only the parameters you
pass are sent, so omitted fields keep their current value.
Use when: renaming a category or changing its icon within its scope.
Returns: the updated category registry dict.
Errors: on a WS failure, returns {"error": "<message>"} instead of
raising.
Inputs: scope (required), category_id (required), icon, name. Returns: object
labels_update_labelUpdate labelADestructive
Update fields on an existing label.
Calls WS config/label_registry/update; only the parameters you pass
are sent, so omitted fields keep their current value.
Use when: renaming a label or changing its icon, color or description.
Returns: the updated label registry dict.
Errors: on a WS failure, returns {"error": "<message>"} instead of
raising.
Inputs: label_id (required), icon, name, color, +1 more. Returns: object
neonplan_create_restore_pointCreate NeonPlan 3D restore pointADestructive
Keep the current state of a NeonPlan 3D plan as a restore point; the oldest is dropped beyond 20.
Calls neonplan3d/history/snapshot (admin) and lists the restore points
afterwards. The integration keeps at most 20, so with 20 already the
oldest is lost.
Use when: before editing the plan in the NeonPlan editor or importing.
Not for: before neonplan_save_plan or neonplan_patch_plan — they take
one themselves; going back — use neonplan_restore_restore_point.
Returns: {"created": true, "plan", "restore_point": {id, revision, saved_at, ...}, "count", "dropped_oldest"}.
Errors: neonplan_version_unsupported, invalid_plan,
plan_not_found, admin_required, neonplan_not_installed,
ha_unreachable.
Inputs: plan, force. Returns: object
neonplan_get_planGet NeonPlan 3D planARead-onlyIdempotent
Read one NeonPlan 3D plan: the whole building object with its revision, or a compact summary.
Calls neonplan3d/building/get. The full building is the object
neonplan_save_plan takes and neonplan_patch_plan paths point into
(units metres, points [x, z], z grows down the drawing). The summary
lists per floor its rooms (id, name, area_id, corner count), openings
(id, type, room_id, edge, offset) and the entity ids the plan references.
Changes nothing.
Use when: reading the plan before an edit; keep revision for
expected_revision.
Not for: the list of plans — use neonplan_list_plans; checking a plan
— use neonplan_validate_plan.
Returns: {"plan", "revision", "version", "version_warning", "building"}
or, with summary_only, {"plan", "revision", "version", "version_warning", "totals", "floors": [...], "entities": [...]}.
Errors: invalid_plan (no I/O), plan_not_found,
neonplan_not_installed, ha_unreachable.
Inputs: plan, summary_only. Returns: object
neonplan_get_statusGet NeonPlan 3D statusARead-onlyIdempotent
Report whether NeonPlan 3D is installed and loaded, its version, license, packs, plans and open screens.
Reads the neonplan3d config entry, then neonplan3d/building/get
(version), license/get (only whether a license is active), packs/list,
plans/list and screens/list (panels and cards open right now — an open
editor with unsaved changes would overwrite a save made through nexus).
A section the integration refuses holds {"error", ...}. Changes nothing.
Use when: before any other neonplan_* tool, or checking that no editor
is open before neonplan_save_plan or neonplan_patch_plan.
Not for: the plan itself — use neonplan_get_plan; HACS updates — use
hacs_get_hacs_repository.
Returns: {"installed", "loaded", "config_entry", "version", "version_warning", "license": {active, error}, "packs": [...], "plans": [...], "screens": [...], "screens_open"}.
Errors: neonplan_not_installed (with config_entry when an entry
exists but is not loaded), ha_unreachable.
Inputs: no named parameters. Returns: object
neonplan_list_plansList NeonPlan 3D plansARead-onlyIdempotent
List the NeonPlan 3D floor plans with their revision and floor, room and furniture counts.
Calls neonplan3d/plans/list: the plans in their order (main always
exists, others have ids like p0123456789) and the plans in the bin.
Changes nothing.
Use when: choosing the plan for the other neonplan_* tools.
Not for: one plan's content — use neonplan_get_plan.
Returns: {"plans": [{id, name, icon, revision, floors, rooms, furniture, ...}], "trash": [...], "locate_plan"}.
Errors: neonplan_not_installed, ha_unreachable, ws_error.
Inputs: no named parameters. Returns: object
neonplan_list_restore_pointsList NeonPlan 3D restore pointsARead-onlyIdempotent
List a NeonPlan 3D plan's restore points (at most 20 kept), newest first.
Calls neonplan3d/history/list (admin). The integration adds one by
itself on a save when the last is older than 10 minutes; the
neonplan_* write tools take one before every save. Changes nothing.
Use when: picking snapshot_id for neonplan_restore_restore_point.
Not for: nexus's Node-RED backups — use nodered_list_backups; HA
backups — use supervisor_list_backups.
Returns: {"plan", "restore_points": [{id, revision, saved_at, saved_at_iso, floors, rooms, furniture}], "count", "max"}.
Errors: invalid_plan, plan_not_found, admin_required,
neonplan_not_installed, ha_unreachable.
Inputs: plan. Returns: object
neonplan_patch_planPatch NeonPlan 3D planADestructive
Change part of a NeonPlan 3D plan with JSON Patch operations, then validate and save it like neonplan_save_plan.
Reads the plan, applies the operations to a copy (a failing operation,
including a failed test, stops everything), validates the result
(errors block) and saves it with the same guards as
neonplan_save_plan: expected_revision, restore point, revision
re-check, read-back. An operation on path "" (the whole plan) needs
overwrite=true when the plan has floors, like neonplan_save_plan.
Use when: binding an entity, adding a lamp or window, renaming a room —
any edit of an existing plan.
Not for: a new plan from scratch — use neonplan_save_plan; checking
paths first — read with neonplan_get_plan.
Returns: like neonplan_save_plan, plus "operations" (count).
Errors: invalid_patch (with operation index), validation_failed,
plan_not_empty (whole-plan operation without overwrite), revision_conflict, invalid_building, neonplan_version_unsupported,
invalid_plan, plan_not_found, admin_required,
neonplan_not_installed, ha_unreachable.
Inputs: operations (required), plan, force, overwrite, +1 more. Returns: object
neonplan_restore_restore_pointRestore NeonPlan 3D restore pointADestructive
Bring a NeonPlan 3D plan back to a restore point; the integration keeps the current state as a new restore point.
Checks the restore point exists (history/list) and expected_revision,
then calls neonplan3d/history/restore (admin), which snapshots the
current building and saves the restored one as a new revision.
Use when: undoing a neonplan_save_plan or neonplan_patch_plan that
went wrong.
Not for: Supervisor backups — use supervisor_restore_backup.
Returns: {"restored": true, "plan", "snapshot_id", "revision_before", "revision", "summary"}.
Errors: invalid_snapshot_id (no I/O), restore_point_not_found,
revision_conflict, neonplan_version_unsupported, invalid_plan,
plan_not_found, admin_required, neonplan_not_installed,
ha_unreachable.
Inputs: snapshot_id (required), plan, force, expected_revision. Returns: object
neonplan_save_planSave NeonPlan 3D planADestructiveIdempotent
Replace a whole NeonPlan 3D plan after validating it, with a restore point and a read-back check.
Runs neonplan_validate_plan (any error blocks), refuses a plan with
floors unless overwrite, checks expected_revision, takes a restore
point (history/snapshot) when the plan has floors, reads the revision
again, sends neonplan3d/building/save and reads the plan back. The
integration itself has no revision check: an editor open with unsaved
changes (see neonplan_get_status screens) can still overwrite this.
Use when: building a plan from scratch or replacing it entirely.
Not for: small edits — use neonplan_patch_plan; undo — use
neonplan_restore_restore_point.
Returns: {"saved": true, "plan", "revision_before", "revision", "snapshot_taken", "verified", "differences", "summary", "warnings"}.
Errors: validation_failed (with errors), plan_not_empty,
revision_conflict, invalid_building (the server's schema refused),
neonplan_version_unsupported, invalid_plan, plan_not_found,
admin_required, neonplan_not_installed, ha_unreachable.
Inputs: building (required), plan, force, overwrite, +1 more. Returns: object
neonplan_suggest_bindingsSuggest NeonPlan 3D entity bindingsARead-onlyIdempotent
Propose which entities of a NeonPlan room's HA area fit which plan field, without writing anything.
Finds the room in the plan, reads HA's entity and device registries and
states, keeps the enabled entities of the room's area_id and groups
them by role: blinds → opening.cover, window/door contacts →
opening.contact, lights → lamp furniture entity, temperature/
humidity/CO2 sensors → room.climate, climate → radiator/ac_unit,
media players → tv_wall, vacuums → robot_vacuum, cameras → pins, locks
→ opening.lock. Each entity says where the plan already uses it.
Use when: filling entity fields explicitly instead of leaving null
(automatic) before neonplan_patch_plan.
Not for: the area's entities in general — use areas_get_area_entities.
Returns: {"plan", "room": {id, name, area_id}, "openings": [...], "suggestions": {role: {"target", "entities": [{entity_id, name, device_class, used_at}]}}, "unassigned": [entity ids]}.
Errors: invalid_plan, plan_not_found, room_not_found,
room_has_no_area, neonplan_not_installed, ha_unreachable.
Inputs: room_id (required), plan. Returns: object
neonplan_upload_background_imageUpload NeonPlan 3D background imageADestructiveIdempotent
Store a png, jpeg or webp image as a NeonPlan 3D background (floor tracing) image and return its image_id.
Reads the file (or decodes the base64), checks the real content type
and the 8 MiB data URL limit, refuses an existing image_id unless
overwrite (image/get), and sends neonplan3d/image/set (admin).
Images are shared by all plans. WARNING: the integration deletes images
no plan references at its next start, so reference it right away in a
floor's background ({"image_id", "x", "z", "width", "opacity", "rotation"}) with neonplan_patch_plan.
Use when: tracing a scanned floor plan in the NeonPlan editor.
Not for: Lovelace or card images — use card_builder_upload_media.
Returns: {"uploaded": true, "image_id", "type", "bytes", "data_url_chars", "replaced", "warning"}.
Errors: invalid_image_id, invalid_source, invalid_path,
path_not_allowed, file_not_found, unsupported_image,
image_too_large, invalid_base64 (all without I/O to HA),
image_exists, neonplan_version_unsupported, admin_required,
neonplan_not_installed, ha_unreachable.
Inputs: image_id (required), path, force, overwrite, +1 more. Returns: object
neonplan_validate_planValidate NeonPlan 3D planARead-onlyIdempotent
Check a NeonPlan 3D building for structure, broken references and unknown HA areas or entities without saving it.
Checks what the integration's schema requires (keys, types, main
ranges), then what it does not check: duplicate ids, an opening's
room_id/edge and offset ± width/2 inside that wall, repeated first
corner, degenerate rooms, entity fields that are not an entity id/null/
none, furniture and pins outside every room; with check_ha, each
area_id against HA's area registry and each entity id against HA's
states. Warnings cover null fields NeonPlan binds automatically from
the area. Writes nothing.
Use when: before neonplan_save_plan, or auditing the stored plan.
Not for: saving — neonplan_save_plan runs this itself.
Returns: {"valid", "errors": [...], "warnings": [...], "summary"}
plus plan/revision when the stored plan was checked.
Errors: invalid_plan, plan_not_found, neonplan_not_installed,
ha_unreachable.
Limits: ranges the schema checks but this does not are caught by the
server at save time (invalid_building).
Inputs: plan, building, check_ha. Returns: object
nodered_find_entity_usageFind HA entity usage in Node-REDARead-onlyIdempotent
List the Node-RED nodes and flows that reference one Home Assistant entity.
Reads GET /flows and scans every node's configuration: a field equal
to the entity id (exact, e.g. entities.entity, target.entityId),
the id inside a template, JSON or function code as a whole word
(text), and Home Assistant node selectors that would match it by
substring or regex (also the older entityId + entityIdType
form). Changes nothing.
Use when: checking what breaks before renaming or removing an entity, or
explaining what controls a device, together with HA automations.
Not for: HA automations and scripts — use search_find_related or
automations_validate_automation_references; nodes by type — use
nodered_search_nodes.
Returns: {"addon_slug", "rev", "entity_id", "nodes": [{id, type, name, flow_id, flow_label, in_subflow, disabled, match: [...], fields: [...]}], "flows": [{flow_id, flow_label, node_count}], "count", "skipped_patterns"}.
Errors: invalid_entity_id (no I/O), plus the add-on lookup errors of
nodered_list_flows.
Limits: a regex is evaluated with Python's engine; one over 200
characters or with nested quantifiers is skipped (counted in
skipped_patterns); entity ids built at runtime are not found.
Inputs: entity_id (required). Returns: object
nodered_get_diagnosticsGet Node-RED diagnosticsARead-onlyIdempotent
Read Node-RED's own diagnostics report: Node.js, OS, memory, runtime state and module versions.
Calls GET /diagnostics (the report behind the editor's Help →
diagnostics), which already reduces sensitive settings to a set/unset
marker; any remaining secret-looking field is replaced by the placeholder.
Changes nothing.
Use when: Node-RED is slow, flows are stopped, or a bug report needs
versions.
Not for: the add-on log — use supervisor_get_addon_logs; installed
palette modules in a compact form — use nodered_get_info.
Returns: {"addon_slug", "report": {...}} as Node-RED sends it.
Errors: HTTP <status> when diagnostics are disabled in settings.js,
plus the add-on lookup errors of nodered_list_flows.
Inputs: no named parameters. Returns: object
nodered_get_flowGet one Node-RED flowARead-onlyIdempotent
Read one Node-RED flow (editor tab) with all its nodes, secrets replaced by a placeholder.
Reads GET /flows and returns the tab plus every node whose z is
this tab (regular nodes, config nodes scoped to the tab, groups,
junctions). Node credentials are never in Node-RED's answer; fields
that look secret (password, token, apikey, URLs with
user:pass@) come back as the redaction placeholder and are listed in
redacted_fields. Changes nothing.
Use when: inspecting a flow, or reading it before nodered_update_flow
(placeholders sent back unchanged keep their stored value).
Not for: the list of flows — use nodered_list_flows; finding nodes
across flows — use nodered_search_nodes or nodered_find_entity_usage.
Returns: {"addon_slug", "rev", "flow": {id, label, disabled, info, env}, "nodes": [...], "node_count", "redacted_fields"}.
Errors: flow_not_found, plus the add-on lookup errors of
nodered_list_flows.
Limits: secrets typed into function code or templates are not detected.
Inputs: flow_id (required). Returns: object
nodered_get_infoGet Node-RED infoARead-onlyIdempotent
Read the Node-RED add-on's version, runtime settings, flow run state and installed palette modules.
Calls GET /settings (kept: version, httpNodeRoot, context,
flowEncryptionType, flowFilePretty, externalModules), GET /flows/state and GET /nodes (grouped per npm module with version and
type count). Changes nothing.
Use when: checking which Node-RED and palette versions run, e.g. whether
node-red-contrib-home-assistant-websocket is installed, before
building a flow.
Not for: host, memory and OS details — use nodered_get_diagnostics;
the add-on's own options — use supervisor_get_addon.
Returns: {"addon_slug", "addon_version", "nodered_version", "settings", "flows_state", "modules": [{module, version, types, enabled, user_installed}]}; a section Node-RED answers with an HTTP error holds
{"error": "HTTP <status>", ...} instead.
Errors: the add-on lookup errors of nodered_list_flows.
Inputs: no named parameters. Returns: object
nodered_list_backupsList Node-RED flow backupsARead-onlyIdempotent
List the Node-RED flow backups nexus wrote before its own writes, newest first.
Reads /data/nodered_backups/ inside the nexus add-on (private to
nexus, kept with nexus's add-on backup, not under /config). Every
nodered_* write tool saves the complete flow list there before it
deploys; the newest 30 are kept. No call to Node-RED.
Use when: choosing a backup_id for nodered_restore_backup, or
checking what changed recently through nexus.
Not for: Supervisor backups of the whole system — use
supervisor_list_backups.
Returns: {"backups": [{backup_id, created, reason, rev, flow_count, node_count}], "count"}; an unreadable file is listed with error.
Errors: none beyond an unreadable file entry; a missing directory
returns an empty list.
Inputs: no named parameters. Returns: object
nodered_list_flowsList Node-RED flowsARead-onlyIdempotent
List the Node-RED add-on's flows (editor tabs) and subflows with node counts and the current deploy rev.
Finds the Node-RED add-on through the Supervisor, then reads
GET /flows (Node-RED Admin API v2) on http://127.0.0.1:46836.
Changes nothing.
Use when: getting flow ids before nodered_get_flow, nodered_update_flow,
nodered_set_flow_enabled or nodered_delete_flow, or an overview.
Not for: nodes inside a flow — use nodered_get_flow; HA automations —
use automations_list_automations.
Returns: {"addon_slug", "rev", "flows": [{id, label, disabled, node_count}], "subflows": [{id, name, node_count, instance_count}], "global_config_nodes", "total_nodes"} in editor tab order. Pass rev
as expected_rev to a write tool to refuse it if someone deploys first.
Errors: nodered_not_found, nodered_not_running,
nodered_unsupported_addon, nodered_unreachable,
nodered_auth_required, timeout, HTTP <status>, or a missing
SUPERVISOR_TOKEN.
Inputs: no named parameters. Returns: object
nodered_search_nodesSearch Node-RED nodesARead-onlyIdempotent
Find Node-RED nodes by type and/or name across all flows and subflows.
Reads GET /flows and matches every node except tab and subflow
definitions: type and name are case-insensitive substrings, both
must match when both are given. Each hit carries its flow (or subflow)
id and label and whether it is disabled (node or flow). Changes nothing.
Use when: locating nodes of one kind, e.g. every api-call-service or
server-state-changed node, or a node by its name.
Not for: which nodes use one HA entity — use
nodered_find_entity_usage; a whole flow — use nodered_get_flow.
Returns: {"addon_slug", "rev", "matches": [{id, type, name, flow_id, flow_label, in_subflow, disabled, config?}], "count", "truncated"};
config only with include_config, plus redacted_fields then.
Errors: no_filter when neither type nor name is given (no I/O),
plus the add-on lookup errors of nodered_list_flows.
Inputs: name, type, limit, flow_id, +1 more. Returns: object
search_deep_searchSearch entities, devices and areasARead-onlyIdempotent
Fuzzy-search entities, devices and areas together in one ranked list.
Scores states (tagging automation.* entities as kind 'automation',
others as 'entity'), devices and areas against query the same way as
the single-kind search tools, merges all matches, and returns the top
limit sorted descending.
Use when: you don't know whether what you're looking for is an entity,
device or area.
Not for: results scoped to one kind — use search_search_entities,
search_search_devices or search_search_areas.
Returns: list of dicts tagged with kind ('entity'/'automation'/
'device'/'area'), each with kind-specific fields plus score, up to
limit entries.
Inputs: query (required), limit. Returns: result
search_find_orphan_devicesFind orphan devicesARead-onlyIdempotent
List devices with no entities associated with them in the entity registry.
Compares every device's id against the set of device_id values
referenced by entity-registry entries and returns devices that no
entity points to.
Use when: hunting for device-registry entries that may be safe to remove, always reviewing each result first. Returns: list of dicts (id, name, name_by_user, manufacturer, model, area_id, config_entries) for devices with no referencing entity. Limits: a WS failure on either registry silently yields an empty underlying list rather than an error, which can under-report orphans.
Inputs: no named parameters. Returns: result
search_find_unused_entitiesFind possibly unused entitiesARead-onlyIdempotent
Heuristically list entities that look unused or orphaned.
Flags entities whose state has been 'unavailable' or 'unknown' for
more than 7 days (or has no last_changed at all), plus any
entity-registry entries with no device_id — which normally means
helpers, automations and template entities, not proof of disuse.
Use when: hunting for cleanup candidates, always reviewing each result
before deleting anything.
Returns: list of dicts (entity_id, state, last_changed, device_id,
reasons) — reasons explains which heuristic(s) matched.
Limits: purely heuristic; the 7-day unavailability threshold and a
missing device_id are weak signals, not confirmation that an entity is
truly unused.
Inputs: no named parameters. Returns: result
search_search_areasSearch areasARead-onlyIdempotent
Fuzzy-rank areas by name.
Scores every area from the area registry against query, keeps only
scores above 0, and returns the top limit matches sorted descending.
Use when: you don't know an area's exact id and want a ranked guess
from a name fragment.
Not for: an exact, unranked area list — use areas_list_areas.
Returns: list of dicts (area_id, name, floor_id, icon, score) up to
limit entries.
Limits: areas that score exactly 0 are dropped entirely; a WS failure
yields an empty list rather than an error.
Inputs: query (required), limit. Returns: result
search_search_devicesSearch devicesARead-onlyIdempotent
Fuzzy-rank devices by name, name_by_user, manufacturer and model.
Scores every device from the device registry against query, keeps
only scores above 0, and returns the top limit matches sorted
descending.
Use when: you don't know a device's exact id and want a ranked guess
from a name fragment.
Not for: an exact, unranked device list — use devices_list_devices,
areas_list_devices or devices_list_devices_in_area.
Returns: list of dicts (id, name, name_by_user, manufacturer, model,
area_id, score) up to limit entries.
Limits: devices that score exactly 0 are dropped entirely; a WS
failure yields an empty list rather than an error.
Inputs: query (required), limit. Returns: result
search_search_entitiesSearch entitiesARead-onlyIdempotent
Fuzzy-rank entities by entity_id, friendly_name and device_id.
Scores every entity against query with substring match (score 1.0)
or a sequence-similarity ratio, keeps only scores above 0, and returns
the top limit matches sorted descending.
Use when: you don't know the exact entity_id and want a ranked guess
from a name fragment.
Returns: list of dicts (entity_id, friendly_name, state, device_id,
score) up to limit entries.
Limits: entities that score exactly 0 are dropped entirely, not just
deprioritised.
Inputs: query (required), limit. Returns: result
services_call_serviceCall any Home Assistant actionADestructive
Call any Home Assistant action by domain and service name over HTTP.
Posts to /api/services/<domain>/<service> with data as the JSON
body; data holds both fields and targets (entity_id/area_id/
device_id). Effect depends entirely on the domain/service passed.
domain/service must match [A-Za-z0-9_]+ (ADR-0006 D3) or the call
is refused before any request is built. Refuses hassio.addon_stop/
app_stop/addon_stdin/app_stdin against nexus's own add-on
(self_protection.is_own_addon); addon_restart/app_restart stay
allowed. homeassistant.restart/stop, hassio.host_reboot/
host_shutdown/restore_full/restore_partial, update.install and
group.remove additionally require confirm=True (ADR-0006 D2) — a
human-in-the-loop checkpoint, not a security boundary; ignored for
every other service.
Use when: no dedicated tool exists for the action needed.
Not for: an action returning response data (e.g.
weather.get_forecasts) — use ws_call_service, which refuses the
same eight guarded services outright (ADR-0006 D5) instead of
accepting confirm.
Returns: the list of states changed during the call.
Errors: {"error": "invalid_service_name"} for a malformed
domain/service; {"error": "self_addon_hassio_service_blocked", "message": ...} for the blocked hassio.* cases; {"error": "confirmation_required", "message": ..., "action": ...} for a guarded
service called without confirm=True.
Inputs: domain (required), service (required), data, confirm. Returns: result
services_camera_recordRecord a camera clipADestructiveIdempotent
Record a short clip from a camera entity to a file, overwriting any existing file at that path.
Calls camera.record with {"entity_id": entity_id, "filename": filename, "duration": duration} over HTTP.
Use when: capturing a short video clip rather than a single still frame.
Not for: a single still frame — use services_camera_snapshot.
Returns: dict with entity_id, filename, duration and the raw
service call result.
Limits: blocks for roughly duration seconds while HA records.
Inputs: filename (required), entity_id (required), duration. Returns: object
services_camera_snapshotSave a camera snapshotADestructiveIdempotent
Save a still snapshot from a camera entity to a file, overwriting any existing file at that path.
Calls camera.snapshot with {"entity_id": entity_id, "filename": filename} over HTTP. filename must be inside the HA config directory
and allow-listed via allowlist_external_dirs, typically under
/config/www/snapshots/... so it can be served by HA.
Use when: capturing a single still frame to a known path, e.g. for a
dashboard image or Lovelace card.
Not for: a video clip — use services_camera_record.
Returns: dict with entity_id, filename and the raw service call
result.
Inputs: filename (required), entity_id (required). Returns: object
services_fire_eventFire a Home Assistant eventADestructive
Fire an arbitrary Home Assistant event with an optional data payload.
Posts to /api/events/<event_type> with event_data as the JSON body;
any automation or integration listening for event_type reacts to it,
so the effect depends entirely on what is registered to listen.
Use when: triggering automations or integrations that listen for a specific event type. Returns: dict confirming the event was fired, as returned by Home Assistant.
Inputs: event_type (required), event_data. Returns: object
services_list_servicesList available servicesARead-onlyIdempotent
List all services Home Assistant currently has registered, optionally filtered by domain.
Calls ha.list_services() (HTTP GET /api/services) and filters the
result client-side by domain when given.
Use when: discovering which services and fields a domain supports before
calling services_call_service.
Returns: list of dicts, one per domain, each with its available services
and their fields.
Inputs: domain. Returns: result
services_media_play_pauseToggle media play/pauseA
Toggle a media player between playing and paused.
Calls media_player.media_play_pause with {"entity_id": entity_id}
over HTTP; the resulting state depends on the player's current state.
Use when: a simple play/pause toggle is enough, without checking current state first. Returns: the list of states changed by the call.
Inputs: entity_id (required). Returns: result
services_media_seekSeek media playback positionAIdempotent
Seek a media player to an absolute playback position.
Calls media_player.media_seek with {"entity_id": entity_id, "seek_position": position} over HTTP.
Use when: jumping to a specific point in the currently playing media. Returns: the list of states changed by the call.
Inputs: position (required), entity_id (required). Returns: result
services_notify_persistent_createCreate a persistent notificationA
Create or replace a persistent notification banner in the Home Assistant UI.
Calls persistent_notification.create with message, optional title
and notification_id. Giving the same notification_id again replaces
that notification's content in place; omitting it creates a new,
separately addressable notification each time.
Use when: showing a UI banner that a person can dismiss, as opposed to a
push notification.
Not for: a push notification to a device — use
services_send_notification.
Returns: dict with notification_id and the raw service call result.
Inputs: message (required), title, notification_id. Returns: object
services_notify_persistent_dismissDismiss a persistent notificationAIdempotent
Dismiss one persistent notification by its ID.
Calls persistent_notification.dismiss with {"notification_id": notification_id} over HTTP; dismissing an already-dismissed or unknown
ID is a no-op from this tool's perspective.
Use when: clearing one specific UI banner.
Not for: clearing every banner — use
services_notify_persistent_dismiss_all.
Returns: dict with notification_id and the raw service call result.
Inputs: notification_id (required). Returns: object
services_notify_persistent_dismiss_allDismiss all persistent notificationsAIdempotent
Dismiss every persistent notification currently shown in the Home Assistant UI.
Calls persistent_notification.dismiss_all over HTTP with no data.
Use when: clearing all UI banners at once.
Not for: clearing a single banner — use
services_notify_persistent_dismiss.
Returns: dict with the raw service call result.
Inputs: no named parameters. Returns: object
services_press_buttonPress a button entityA
Press a button entity, running whatever action it is configured to perform.
Calls button.press with {"entity_id": entity_id} over HTTP.
Use when: running a button entity's configured action, such as a template button or a device's physical-button equivalent. Returns: the list of states changed by the press.
Inputs: entity_id (required). Returns: result
services_reload_configReload domain configurationAIdempotent
Reload one domain's configuration from disk by calling its reload action.
Calls <domain>.reload (e.g. automation.reload, input_boolean.reload)
over HTTP with no data.
Use when: applying YAML changes for automations, scripts, scenes or
input helpers without restarting Home Assistant.
Not for: reloading every helper domain in one call — use
helpers_reload_helpers.
Returns: the list of states changed by the reload.
Inputs: domain (required). Returns: result
services_render_templateRender a Jinja2 templateARead-onlyIdempotent
Render a Jinja2 template string once through HA's template engine over HTTP.
Posts to /api/template with {"template": template} and returns the
rendered text.
Use when: testing a template's output before saving it into an
automation, script or template sensor.
Not for: rendering through the WebSocket subscription transport — use
ws_render_template.
Returns: the rendered template as plain text.
Inputs: template (required). Returns: result
services_send_notificationSend a notificationA
Send a notification through a Home Assistant notify service.
Calls notify.<target> (or plain notify.notify when target is
omitted) with message and optional title; target may include the
domain (notify.xyz) or be a bare service name, but a dotted target
must name the notify domain itself (ADR-0006 D6) — otherwise it would
let any domain.service be reached under cover of a "notification".
Each call dispatches a new notification to whatever device or channel
that service delivers to, which can be outside the local network (e.g.
a phone push).
Use when: pushing a message to a person or device through a configured
notify service.
Not for: an in-UI banner tracked by an ID — use
services_notify_persistent_create.
Returns: the list of states changed by the call (notify services
typically change none).
Errors: {"error": "invalid_notify_target", "message": ...} when a
dotted target names a domain other than notify; {"error": "invalid_service_name"} when the part after notify. is not itself a
bare [A-Za-z0-9_]+ service name (e.g. a second dot).
Inputs: message (required), title, target. Returns: result
services_set_climate_modeSet climate modeAIdempotent
Set a climate entity's heating/cooling mode.
Calls climate.set_hvac_mode with {"entity_id": entity_id, "hvac_mode": hvac_mode} over HTTP.
Use when: switching a thermostat between heat/cool/auto/off/fan_only/dry.
Not for: the target temperature — use entities_set_value.
Returns: the list of states changed by the call.
Inputs: entity_id (required), hvac_mode (required). Returns: result
services_set_cover_positionSet cover positionAIdempotent
Set a cover/blind/shutter to a specific open position.
Calls cover.set_cover_position with {"entity_id": entity_id, "position": position} over HTTP.
Use when: moving a cover to a specific percentage rather than fully open/closed. Returns: the list of states changed by the call.
Inputs: position (required), entity_id (required). Returns: result
services_set_cover_tiltSet cover tilt positionAIdempotent
Set a cover's slat/tilt position independently of its open/closed position.
Calls cover.set_cover_tilt_position with {"entity_id": entity_id, "tilt_position": tilt_position} over HTTP.
Use when: adjusting slat angle on a cover that supports tilt.
Not for: the cover's overall open/closed position — use
services_set_cover_position.
Returns: the list of states changed by the call.
Inputs: entity_id (required), tilt_position (required). Returns: result
services_set_light_colorSet light color and brightnessAIdempotent
Set a light's color, color temperature and/or brightness in one call.
Calls light.turn_on with only the given fields set (rgb_color,
color_temp_kelvin, brightness); a given color_temp (mireds) is
converted to Kelvin (round(1_000_000 / mireds)) first, since HA's
light.turn_on no longer accepts mireds.
Use when: adjusting a light's color/brightness, whether it is currently
on or off — light.turn_on also turns it on.
Not for: a plain on/off/toggle with no color change — use
entities_turn_on, which supports the same brightness/color options for
lights alongside generic on/off for any domain.
Returns: the list of states changed by the call.
Inputs: entity_id (required), rgb_color, brightness, color_temp, +1 more. Returns: result
services_set_volumeSet media player volumeAIdempotent
Set a media player's volume level.
Calls media_player.volume_set with {"entity_id": entity_id, "volume_level": volume} over HTTP.
Use when: setting an exact volume rather than stepping it up/down. Returns: the list of states changed by the call.
Inputs: volume (required), entity_id (required). Returns: result
snapshot_get_area_snapshotGet area-scoped HA snapshotARead-onlyIdempotent
Return states, devices and entities for one area in a single call.
Convenience wrapper that calls snapshot_get_snapshot with
include=["states", "devices", "entities", "areas"] and area_id fixed
to the given area; it adds no filtering beyond summary.
Use when: exploring or controlling everything in one physical area
without composing snapshot_get_snapshot's include/area_id
arguments by hand.
Not for: a snapshot spanning several areas or other sections — call
snapshot_get_snapshot directly; entity registry rows without state
values — use areas_get_area_entities; live state values without
registry context — use areas_get_area_states.
Returns: same dict shape as snapshot_get_snapshot with
include=["states", "devices", "entities", "areas"].
Limits: no pagination; every state/device/entity in the area is
returned.
Inputs: area_id (required), summary. Returns: object
snapshot_get_snapshotGet filtered HA snapshotARead-onlyIdempotent
Return a single filtered snapshot combining HA states, registries and config.
Reads live states via ha.get_states() and, depending on include, the
area/floor/device/entity registries and config entries over HTTP in one
call, applies domains/area_id filtering and limit/offset
pagination to the states list, and returns one dict keyed by section
name. Every call in this path is a read; nothing here writes to HA.
Use when: a client needs several registries and/or states together and
should not spend several round-trips assembling that context.
Not for: a single registry without filtering — use entities_list_entities
or ws_get_states for a plain state list, or areas_list_devices/
devices_list_devices for a plain device list.
Returns: dict keyed by requested section (states, areas, floors,
devices, entities, integrations, config), plus _meta (echoed
filters and per-section counts) and _states_total (pre-pagination
count) when states is included.
Errors: {"error": "unknown_include", "unknown": [...], "valid": [...]}
when include names a section outside the valid set.
Limits: limit/offset paginate only the states section; every other
section is always returned in full.
Inputs: limit, offset, area_id, domains, +3 more. Returns: object
statistics_get_energy_statisticsGet energy sum statistics for recent daysARead-onlyIdempotent
Get sum statistics for every energy-related sensor over the last N days.
Auto-discovers 'sum' statistic IDs via WS recorder/list_statistic_ids,
keeps only those whose unit is an energy/volume unit (kWh, MWh, Wh, m³,
ft³, L, gal — instantaneous power sensors in 'W' are excluded since a
'sum' statistic on a power sensor is not a meaningful energy value),
then fetches sum/change via WS recorder/statistics_during_period
for the requested window. This is a convenience wrapper around
statistics_get_statistics.
Use when: a quick overview of overall energy consumption trends is
needed without first listing statistic IDs by hand.
Not for: a hand-picked set of statistic IDs or non-energy sensors — use
statistics_get_statistics directly.
Returns: {"days", "period", "statistic_count", "data": {statistic_id: {"unit": ..., "rows": [{"start": <date>, "change": ..., "sum": ...}, ...]}}}, or {"message": "..."} when no energy statistic IDs are
found.
Errors: {"error": "days must be between 1 and 365"} for an
out-of-range days; {"error": "..."} when either WS call raises or
returns an unexpected shape.
Inputs: days, period. Returns: object
statistics_get_statisticsGet aggregated statistics for a time rangeARead-onlyIdempotent
Get aggregated recorder statistics for one or more IDs over a time range.
Calls WS recorder/statistics_during_period with start/end parsed
into UTC timestamps, converts each row's epoch start back to an ISO
string, and rounds numeric aggregates to 4 decimals.
Use when: analysing energy/temperature/etc. trends over hours, days,
weeks or months using the recorder's pre-aggregated data.
Not for: raw short-term state changes between two points in time — use
history_get_state_history instead.
Returns: {"period", "start", "end", "types", "data": {statistic_id: [{"start": <iso>, "sum": ..., "mean": ..., ...}, ...]}}.
Errors: {"error": "..."} for an empty statistic_ids, an invalid
period/types value, an unparsable start/end, a non-dict WS
response, or when the WS call raises.
Inputs: start (required), statistic_ids (required), end, types, +1 more. Returns: object
statistics_get_statistics_metadataGet statistics metadataARead-onlyIdempotent
Get metadata (unit, source, name) for specific recorder statistic IDs.
Calls WS recorder/get_statistics_metadata and returns one entry per
requested ID.
Use when: you already know the statistic IDs and only need their
unit/source/name, without their historical values.
Not for: the actual aggregated values — use statistics_get_statistics.
Returns: list of {"statistic_id", "name", "source", "unit", "has_sum", "has_mean"} dicts.
Errors: [{"error": "..."}] when the WS response isn't a list or the
WS call raises.
Inputs: statistic_ids (required). Returns: result
statistics_list_statistic_idsList recorder statistic IDsARead-onlyIdempotent
List recorder statistic IDs of the requested type.
Calls WS recorder/list_statistic_ids and returns one entry per
statistic the recorder tracks, with its source and unit.
Use when: discovering which entities have long-term statistics before
calling statistics_get_statistics or statistics_get_statistics_metadata.
Not for: raw short-term state history — use
history_get_state_history instead.
Returns: list of {"statistic_id", "name", "source", "unit", "has_sum", "has_mean"} dicts.
Errors: [{"error": "..."}] when statistic_type is not 'sum'/'mean',
when the WS response isn't a list, or when the WS call raises.
Inputs: statistic_type. Returns: result
supervisor_create_backupCreate a Supervisor backupA
Create a new Supervisor backup, full or partial.
Calls POST /backups/new/full when neither addons nor folders is
given, otherwise POST /backups/new/partial with those slugs/folders.
Unlike system_create_backup, this never deletes older backups — it
only adds a new one.
Use when: a named, partial and/or password-protected backup is needed on
a Supervisor install.
Not for: a quick backup using the instance's own automatic-backup
settings (which may prune old ones) — use system_create_backup.
Returns: Supervisor's backup-job result, including the new backup's
slug on success.
Errors: {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing;
{"error": "HTTP <status>", "detail": ...} on a timeout or failure —
check supervisor_list_backups before retrying.
Limits: a full backup can take minutes; on a timeout error, check
supervisor_list_backups before retrying rather than assuming failure.
Inputs: name (required), addons, folders, password. Returns: object
supervisor_delete_backupDelete a Supervisor backupADestructiveIdempotent
Permanently delete one backup after an explicit confirmation.
Calls DELETE /backups/<slug>. Without confirm=True nothing is
deleted; the call only returns a confirmation prompt. There is no undo
once the backup file is gone — a backup is itself the undo mechanism
for every other change in this add-on.
Use when: cleaning up a backup that is confirmed to be no longer
needed.
Not for: any situation where the backup might still be needed — there
is no recovery after this call, even with confirm=True.
Returns: Supervisor's delete result when confirmed, otherwise a
confirmation prompt.
Errors: {"error": "invalid_slug"} for a bad slug; returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the
token env var is missing; {"error": "HTTP <status>", "detail": ...}
if the slug does not exist.
Limits: requires confirm=True; deletion is immediate and permanent
with no undo once confirmed.
Inputs: slug (required), confirm. Returns: object
supervisor_get_addonGet add-on detailsARead-onlyIdempotent
Get full Supervisor info for one add-on, with secret option values redacted.
Calls GET /addons/<slug>/info: every field Supervisor stores for that
add-on (options schema, current options, ports, boot mode, version,
state and more), except options values are replaced with a fixed
placeholder wherever the schema marks a field a password, the key name
looks like a secret (password/pass/pwd, token, api_key,
secret, credential, private, key as a word/suffix), or the value
is a URL with inline credentials (scheme://user:pass@host) — covers
nexus's own API key and other add-ons' secrets/connection strings
alike, recursively through nested groups and lists. An empty/unset
value stays empty. Adds redacted_fields: {"path", "reason"} dicts.
Use when: the full add-on record is needed, e.g. before editing its
options with supervisor_set_addon_options, which accepts the same
placeholder back for an unchanged secret field without overwriting it.
Not for: a quick overview across all add-ons — use
supervisor_list_addons.
Returns: Supervisor's add-on info payload with secret-looking options
values replaced by a placeholder, plus redacted_fields.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing; {"error": "HTTP <status>", "detail": ...} if the slug does not exist.
Inputs: slug (required). Returns: object
supervisor_get_addon_logsGet add-on log linesARead-onlyIdempotent
Get the most recent log lines from one add-on.
Calls GET /addons/<slug>/logs, which returns plain text, and keeps
only the last lines lines.
Use when: debugging one add-on's runtime behaviour.
Not for: the ESPHome add-on's per-device compile/upload logs — use
esphome_get_addon_logs if that distinction matters to the caller.
Returns: {"logs": "<joined log lines>"}.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "SUPERVISOR_TOKEN not set or empty response"} when
the token is missing; {"error": "HTTP <status>", "detail": ...} on a
Supervisor API error.
Inputs: slug (required), lines. Returns: object
supervisor_get_addon_statsGet add-on resource statsARead-onlyIdempotent
Get an add-on's current runtime resource usage.
Calls GET /addons/<slug>/stats for CPU, memory, network and disk I/O
figures at the moment of the call.
Use when: checking whether an add-on is consuming unexpected resources.
Not for: historical usage over time — this returns only a snapshot.
Returns: Supervisor's raw stats payload (CPU percent, memory
usage/limit, network and block I/O counters).
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing;
{"error": "HTTP <status>", "detail": ...} if the add-on is not
running.
Inputs: slug (required). Returns: object
supervisor_get_core_infoGet HA Core infoARead-onlyIdempotent
Get info about the Home Assistant Core container.
Calls GET /core/info for its version, CPU architecture and machine
type.
Use when: checking Core's version/arch, as opposed to the Supervisor or
host.
Not for: HA's own location/units/component config — use
history_get_ha_config.
Returns: Supervisor's raw Core info payload (version, arch, machine).
Errors: {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing.
Inputs: no named parameters. Returns: object
supervisor_get_host_infoGet host OS infoARead-onlyIdempotent
Get info about the host operating system.
Calls GET /host/info for Home Assistant OS version, hostname, kernel and related
host-level fields.
Use when: checking the underlying OS/hardware, as opposed to Core or the
Supervisor.
Not for: Supervisor's own version — use
supervisor_get_supervisor_info.
Returns: Supervisor's raw host info payload (Home Assistant OS version, hostname,
kernel, and related fields).
Errors: {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing.
Inputs: no named parameters. Returns: object
supervisor_get_supervisor_infoGet Supervisor infoARead-onlyIdempotent
Get info about the Supervisor component itself.
Calls GET /supervisor/info for its version, update channel and health
flag.
Use when: checking the Supervisor's own version/channel/health, as
opposed to Core or the host.
Not for: Home Assistant Core details — use supervisor_get_core_info;
for the host OS — use supervisor_get_host_info.
Returns: Supervisor's raw info payload (version, channel, healthy,
and related fields).
Errors: {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing.
Inputs: no named parameters. Returns: object
supervisor_install_addonInstall an add-onAIdempotent
Install an add-on from its slug.
Calls POST /addons/<slug>/install. The add-on must already belong to a
repository Supervisor knows about; this does not add repositories.
Installing downloads the add-on's image, which reaches outside the HA
instance and its host.
Use when: adding a new add-on that is already visible in an installed
repository.
Not for: starting/stopping an already-installed add-on — use
supervisor_start_addon/supervisor_stop_addon.
Returns: Supervisor's install-job result.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing;
{"error": "HTTP <status>", "detail": ...} if the slug is unknown.
Limits: downloads the add-on image over the network; can take a while
on a slow connection.
Inputs: slug (required). Returns: object
supervisor_list_addonsList installed add-onsARead-onlyIdempotent
List every installed add-on with its slug, name, state and version.
Calls Supervisor's GET /addons and projects each entry down to slug,
name, state, version, version_latest and update_available.
Use when: getting an overview of installed add-ons and which have
updates pending.
Not for: full add-on detail (options, ports, boot mode) — use
supervisor_get_addon.
Returns: {"addons": [{slug, name, state, version, version_latest, update_available}, ...]}.
Errors: {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing;
{"error": "HTTP <status>", "detail": ...} on a Supervisor API error.
Inputs: no named parameters. Returns: object
supervisor_list_backupsList Supervisor backupsARead-onlyIdempotent
List every backup Supervisor manages.
Calls GET /backups for the full backup catalogue Supervisor tracks.
Use when: finding a backup's slug before restoring or deleting it, or
checking whether a scheduled backup succeeded.
Not for: HA Core's own backup.create/backup.create_automatic backups
when they were not made through Supervisor — those may not appear here
under the same view.
Returns: Supervisor's raw backups payload.
Errors: {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing.
Inputs: no named parameters. Returns: object
supervisor_restart_addonRestart an add-onADestructiveIdempotent
Restart an add-on (stop, then start).
Calls POST /addons/<slug>/restart. The add-on — which could be this
nexus add-on itself — is briefly unavailable during the restart.
Use when: an add-on needs to pick up new options or recover from a
stuck state.
Not for: a one-way stop — use supervisor_stop_addon; for restarting
Core instead — use supervisor_restart_core.
Returns: Supervisor's restart-job result.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing;
{"error": "HTTP <status>", "detail": ...} if the slug is unknown.
Limits: briefly interrupts the add-on's availability.
Inputs: slug (required). Returns: object
supervisor_restart_coreRestart HA CoreADestructiveIdempotent
Restart Home Assistant Core through the Supervisor after an explicit confirmation.
Calls POST /core/restart. WARNING: causes downtime for HA Core (and
everything depending on it) until it comes back up. Without
confirm=True nothing is restarted.
Use when: Core needs restarting on a Supervisor install specifically.
Not for: the equivalent call via HA's own service — use
system_restart_ha; for rebooting the whole host — use
supervisor_restart_host.
Returns: Supervisor's restart-job result when confirmed.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the
token env var is missing.
Limits: requires confirm=True; interrupts Core until it restarts.
Inputs: confirm. Returns: object
supervisor_restart_hostReboot the hostADestructiveIdempotent
Reboot the whole host machine after an explicit confirmation.
Calls POST /host/reboot. WARNING: Home Assistant, every add-on
(including this nexus add-on) and the host OS go offline for minutes.
Without confirm=True nothing is rebooted.
Use when: a host-level change (e.g. a Home Assistant OS update) requires a full reboot.
Not for: restarting only Core — use supervisor_restart_core; for
restarting one add-on — use supervisor_restart_addon.
Returns: Supervisor's reboot-job result when confirmed.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the
token env var is missing.
Limits: requires confirm=True; takes the whole host, including this
add-on, offline for minutes — the call itself may not receive a reply.
Inputs: confirm. Returns: object
supervisor_restore_backupRestore a full backupADestructiveIdempotent
Restore a full backup after an explicit confirmation.
Calls POST /backups/<slug>/restore/full, which replaces the HA
configuration, every add-on with its data, and the backed-up folders
with the backup's contents; anything changed since the backup was taken
is lost. Core and this nexus add-on restart as part of the restore, so
the call may drop the connection before it can reply. Without
confirm=True nothing is restored.
Use when: reverting to a known-good state after a failed update or
misconfiguration.
Not for: restoring only some add-ons/folders — Supervisor's partial
restore is not exposed by this tool.
Returns: Supervisor's restore-job result when confirmed; the reply may
never arrive because the add-on restarts mid-call.
Errors: {"error": "invalid_slug"} for a bad slug; returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false; {"error": "HTTP <status>", "detail": ...} if the slug or password is wrong.
Limits: WARNING: discards every change made since the backup; requires
confirm=True.
Inputs: slug (required), confirm, password. Returns: object
supervisor_set_addon_optionsSet add-on optionsADestructiveIdempotent
Replace an add-on's stored options with the given object.
Calls POST /addons/<slug>/options as {"options": options}. Read
current values via supervisor_get_addon, modify them, and send the
full dict back — overwrites previous options entirely, so omitted
fields are lost. A value left as the placeholder for a secret field is
swapped for the real stored value first, so echoing it back unchanged
never overwrites the secret — a list containing it must keep every
item's order/count as read, or the call is refused rather than guessed.
Once a placeholder was resolved, a Supervisor error strips detail
(it can otherwise echo the rejected payload, secret included). Takes
effect after supervisor_restart_addon. Refuses to run against
nexus's own add-on — could otherwise lift its own restrictions.
Use when: changing an add-on's configuration programmatically.
Not for: reading the current options first — use
supervisor_get_addon; for changing nexus's own configuration — use the
Home Assistant Supervisor UI instead.
Returns: Supervisor's options-update result.
Errors: {"error": "invalid_slug"} for a bad slug; self_addon_options_blocked for nexus's own add-on;
redaction_marker_list_length_mismatch on a placeholder list-length
mismatch; SUPERVISOR_TOKEN not set when the token is missing;
{"error": "HTTP <status>"} on a schema-validation or placeholder
read-back failure.
Limits: does not apply until the add-on is restarted.
Inputs: slug (required), options (required). Returns: object
supervisor_start_addonStart an add-onAIdempotent
Start an installed, stopped add-on.
Calls POST /addons/<slug>/start.
Use when: bringing an installed add-on online after it was stopped.
Not for: installing a new add-on — use supervisor_install_addon; for
stopping it — use supervisor_stop_addon.
Returns: Supervisor's start-job result.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing;
{"error": "HTTP <status>", "detail": ...} if the slug is unknown or
already running.
Inputs: slug (required). Returns: object
supervisor_stop_addonStop an add-onADestructiveIdempotent
Stop a running add-on.
Calls POST /addons/<slug>/stop. The add-on — e.g. an MQTT broker other
integrations depend on — becomes unavailable until started again.
Refuses to run at all against nexus's own add-on (by its real slug or
the literal alias Supervisor resolves to the caller itself): nexus
stopping itself would cut off the very connection carrying this call,
with no guarantee the response ever comes back, and — unlike
supervisor_restart_addon — leaves nexus down until someone starts it
again some other way.
Use when: taking one add-on offline without uninstalling it.
Not for: removing it entirely — use supervisor_uninstall_addon; for
bringing it back — use supervisor_start_addon; for a brief restart of
nexus itself — use supervisor_restart_addon instead, which is allowed.
Returns: Supervisor's stop-job result.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "self_addon_stop_blocked", "message": ...} when
slug is nexus's own add-on; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var
is missing; {"error": "HTTP <status>", "detail": ...} if the slug is
unknown.
Limits: interrupts the add-on's availability, and anything depending on
it, until it is started again.
Inputs: slug (required). Returns: object
supervisor_uninstall_addonUninstall an add-onADestructiveIdempotent
Uninstall an add-on and its persistent data after an explicit confirmation.
Calls POST /addons/<slug>/uninstall. Refuses to run at all against
nexus's own add-on (its real slug, or the alias Supervisor resolves to
the caller itself — see self_protection.is_own_addon) — checked first,
with no Supervisor request made either way, before even the
confirmation gate: nexus removing itself is never the right tool for
that regardless of confirm. Otherwise, without confirm=True nothing
is removed; the call only returns an error asking for confirmation
(ADR-0003 D1).
Use when: permanently removing an add-on that is no longer needed.
Not for: temporarily stopping it while keeping its data and config — use
supervisor_stop_addon.
Returns: Supervisor's uninstall-job result when confirmed.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "self_addon_uninstall_blocked", "message": ...} when
slug is nexus's own add-on; returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm
is false; {"error": "HTTP <status>", "detail": ...} on a Supervisor
API error.
Limits: WARNING: deletes the add-on's data with no separate backup step;
requires confirm=True.
Inputs: slug (required), confirm. Returns: object
supervisor_update_addonUpdate an add-onADestructive
Update an add-on to its latest available version.
Calls POST /addons/<slug>/update, which downloads and installs the new
version over the network; the previous version is only recoverable from
a backup taken beforehand.
Use when: update_available is true for the add-on and the new version
should be applied.
Not for: reverting an update — restore a backup via
supervisor_restore_backup instead; there is no dedicated rollback
call.
Returns: Supervisor's update-job result.
Errors: {"error": "invalid_slug"} for a bad slug; {"error": "SUPERVISOR_TOKEN not set — Nexus must run as HA add-on for Supervisor API"} when the token env var is missing;
{"error": "HTTP <status>", "detail": ...} on a failed update.
Limits: downloads the new version over the network; no automatic
rollback on failure.
Inputs: slug (required). Returns: object
system_check_configValidate HA configurationARead-onlyIdempotent
Validate the current Home Assistant configuration without applying anything.
Calls POST /api/config/core/check_config, the same YAML validation HA
runs internally before a restart; nothing is reloaded or restarted by
this call.
Use when: verifying configuration.yaml and related files are valid
before calling system_restart_ha.
Not for: applying a change into the running instance — use
system_reload_all for a no-downtime reload or system_restart_ha for a
full restart.
Returns: HA's check payload, typically {"result": "valid"|"invalid", "errors": ...}.
Errors: raises httpx.HTTPStatusError if the HA API request itself
fails (e.g. HA unreachable).
Inputs: no named parameters. Returns: object
system_create_backupCreate automatic HA backupADestructive
Create a Home Assistant backup using whichever backup service the instance registers.
On Supervisor installs backup.create does not exist, so this calls
backup.create_automatic instead, which creates a backup using the
automatic-backup settings configured in Settings -> System -> Backups;
when a retention count is configured there, those same settings prune
older automatic backups as a side effect of this call. On HA
Core/Container installs, where backup.create exists, that one is
called instead — no name, folder selection or password. Returns an
error if neither service is registered.
Use when: HA already has the wanted automatic-backup settings configured
and a quick backup with no extra parameters is enough.
Not for: a named, partial, and/or password-protected backup on a
Supervisor install, or a backup that never deletes older ones — use
supervisor_create_backup.
Returns: {"service": "backup.create"|"backup.create_automatic", "changed_states": [...]}, or an error dict when neither service is
registered.
Errors: {"error": "Neither backup.create nor backup.create_automatic is registered on this Home Assistant instance."}.
Limits: on Supervisor installs, applies the instance's configured
retention count, which can delete older backups.
Inputs: no named parameters. Returns: object
system_get_all_integrationsList config entries compactlyARead-onlyIdempotent
List every config entry as a compact summary of its key fields.
Calls the same config_entries/get WebSocket command as
system_list_integrations and projects each entry down to entry_id,
domain, title, state and source; every state is included, so filter on
state yourself.
Use when: scanning or filtering integrations by domain/state without the
full raw payload.
Not for: every field HA stores on the entry — use
system_list_integrations.
Returns: list of {entry_id, domain, title, state, source} dicts.
Errors: raises RuntimeError if the underlying WebSocket call fails
(e.g. auth or WS-level error).
Inputs: no named parameters. Returns: result
system_get_repairsList active repair issuesARead-onlyIdempotent
List Home Assistant's active repair issues.
Calls the repairs/list_issues WebSocket command and projects each
issue down to its id, domain, severity, breaks_in_ha_version,
learn-more URL, translation key, and ignored/is_fixable flags.
Use when: surfacing deprecated config, broken integrations or required
migrations that need attention.
Not for: the full raw repair-issue payload with every field HA stores —
this always returns the projected subset above.
Returns: list of {issue_id, domain, severity, breaks_in_ha_version, learn_more_url, translation_key, ignored, is_fixable} dicts.
Errors: raises RuntimeError if the underlying WebSocket call fails
(e.g. auth or WS-level error).
Inputs: no named parameters. Returns: result
system_get_system_healthGet system health checksARead-onlyIdempotent
Get Home Assistant's system-health report across its core subsystems.
Runs the system_health/info WebSocket subscription to completion and
merges its initial/update/finish events into one dict, since HA exposes
system health only as a WebSocket stream, not over HTTP.
Use when: checking recorder/websocket/cloud/network-style health checks
and basic system info (version, dev mode, virtualenv) in one call.
Not for: a plain liveness check — use system_ping_ha; for HA
version/location/config use history_get_ha_config.
Returns: dict keyed by integration domain, each with an info dict
mapping check name to value (or {"error": ...} for a failed check).
Errors: raises RuntimeError on WebSocket auth failure or a WS-level
error from system_health/info.
Limits: waits up to an internal 15-second timeout for the stream's
finish event; on timeout it returns whatever partial data arrived
instead of raising.
Inputs: no named parameters. Returns: object
system_get_updatesList available HA updatesARead-onlyIdempotent
List Home Assistant's update.* entities, one per updatable component.
Reads all HA states and filters to entities in the update domain
(core, add-ons, HACS repositories, custom components), extracts
installed/latest version and release info from their attributes, and
sorts pending updates first.
Use when: checking what has an update available across the whole
instance in one call.
Not for: live Supervisor add-on state beyond this snapshot — use
supervisor_get_addon or supervisor_list_addons.
Returns: list of {entity_id, name, installed_version, latest_version, update_available, release_url, release_notes, skipped_version, in_progress, auto_update}, sorted with available updates first.
Inputs: pending_only. Returns: result
system_list_integrationsList all config entriesARead-onlyIdempotent
List every Home Assistant config entry, whatever its state.
Calls the raw config_entries/get WebSocket command and returns it
unfiltered: every field HA stores per entry, in any state (loaded,
not_loaded, setup_error, disabled). On instances with many
integrations this can be a large payload.
Use when: the raw config-entry objects, with every field, are needed.
Not for: a compact, easier-to-scan listing — use
system_get_all_integrations, which strips this down to
entry_id/domain/title/state/source.
Returns: list of raw config-entry dicts as returned by HA's WebSocket
API.
Errors: raises RuntimeError if the underlying WebSocket call fails
(e.g. auth or WS-level error).
Limits: no pagination or filtering; large HA instances get a large
response.
Inputs: no named parameters. Returns: result
system_ping_haCheck HA API reachabilityARead-onlyIdempotent
Check whether the Home Assistant API is reachable over HTTP.
Calls GET /api/ through ha.ping(), which catches any connection
error internally and reports plain reachability, not health or
subsystem status.
Use when: confirming HA is up before other calls, quick liveness
probing.
Not for: the raw /api/ payload itself — use history_get_system_info;
for HA version/location/config use history_get_ha_config; for
subsystem health use system_get_system_health.
Returns: {"reachable": bool, "url": <configured HA_URL>}.
Inputs: no named parameters. Returns: object
system_reload_allReload core configurationAIdempotent
Reload core Home Assistant configuration without restarting the instance.
Calls the homeassistant.reload_all service, which HA fans out to every
component that supports a config reload (automations, scripts, scenes,
groups and more), re-reading their YAML from disk.
Use when: YAML for automations/scripts/scenes/groups changed and a fast,
no-downtime reload is enough.
Not for: changes that require a full restart, e.g. new integrations or
structural configuration.yaml edits — use system_restart_ha; for one
integration only — use system_reload_integration.
Returns: {"status": "reload_all triggered"}; it does not wait for or
report individual component reload results.
Inputs: no named parameters. Returns: object
system_reload_integrationReload one config entryAIdempotent
Reload a single integration's config entry without restarting Home Assistant.
Calls the homeassistant.reload_config_entry service for the given
entry_id, which unloads and re-sets-up that one integration only.
Use when: one integration needs to pick up new options or recover from a
transient setup error.
Not for: reloading every reloadable component at once — use
system_reload_all.
Returns: the homeassistant.reload_config_entry service-call result.
Errors: raises httpx.HTTPStatusError if entry_id does not exist or
the domain does not support config-entry reload.
Inputs: entry_id (required). Returns: result
system_restart_haRestart Home AssistantADestructiveIdempotent
Restart Home Assistant after an explicit confirmation.
Calls the homeassistant.restart service, which causes roughly 30
seconds of downtime for the whole instance, including this add-on.
Without confirm=True nothing is restarted; the call only returns a
safety prompt describing how to confirm.
Use when: a config change requires a full restart, e.g. after
system_check_config reports the config is valid.
Not for: a no-downtime reload — use system_reload_all; stopping HA
without restarting it — use system_stop_ha; restarting only Core under
Supervisor — use supervisor_restart_core.
Returns: {"service": "homeassistant.restart", "changed_states": [...]}
when confirmed, otherwise a confirmation prompt.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false.
Limits: interrupts Home Assistant for about 30 seconds; requires
confirm=True.
Inputs: confirm. Returns: object
system_stop_haStop Home AssistantADestructiveIdempotent
Stop Home Assistant after an explicit confirmation.
Calls the homeassistant.stop service. Unlike a restart, nothing brings
the instance back automatically — a manual restart is required. Without
confirm=True nothing is stopped; the call only returns a safety
prompt.
Use when: HA needs to be taken fully offline, e.g. before host
maintenance.
Not for: a temporary interruption that comes back on its own — use
system_restart_ha.
Returns: {"service": "homeassistant.stop", "changed_states": [...]}
when confirmed, otherwise a confirmation prompt.
Errors: returns {"error": "confirmation_required", "message": ..., "action": ...} when confirm is false.
Limits: requires a manual restart to bring HA back online; requires
confirm=True.
Inputs: confirm. Returns: object
themes_create_themeCreate theme fileADestructiveIdempotent
Create a new Lovelace theme file.
Writes themes/<name>.yaml as {<name>: variables}. The file is only
loaded by the frontend if configuration.yaml has frontend: themes: !include_dir_merge_named themes. Fails instead of overwriting unless
overwrite=True.
Use when: adding a brand-new theme.
Not for: changing an existing theme in place — use
themes_update_theme.
Returns: dict with success, path, and reloaded (present when
reload=True).
Errors: {"success": false, "error": "Theme '<name>' already exists. Pass overwrite=True to replace."} when the file exists and
overwrite is false; {"success": false, "error": "invalid_theme_name", "detail": ...} when name contains '/' or a
backslash, starts with '.', or is blank.
Limits: name must not contain '/' or a backslash, start with '.', or
be blank.
Inputs: name (required), variables (required), reload, overwrite. Returns: object
themes_delete_themeDelete theme fileADestructiveIdempotent
Delete a theme file.
Removes themes/<name>.yaml from disk if it exists.
Use when: a theme is no longer needed.
Returns: dict with success and deleted (the removed path), plus
reloaded when reload=True.
Errors: {"success": false, "error": "Theme '<name>' not found at <path>"} when the file doesn't exist; {"success": false, "error": "invalid_theme_name", "detail": ...} when name contains '/' or a
backslash, starts with '.', or is blank.
Inputs: name (required), reload. Returns: object
themes_get_themeGet theme variablesARead-onlyIdempotent
Get one theme's CSS variable map by name.
Calls WS frontend/get_themes and looks up name in the result.
Use when: inspecting a single theme's variables rather than the whole
registry from themes_list_themes.
Returns: dict with name and variables (the CSS variable map).
Errors: {"error": "Theme '<name>' not found", "available": [...]} if
the name isn't registered.
Inputs: name (required). Returns: object
themes_list_theme_filesList theme files on diskARead-onlyIdempotent
List YAML theme files present on disk under themes/.
Scans <config>/themes/ recursively for .yaml/.yml files,
returning their paths relative to the config directory; returns an
empty list if the directory doesn't exist yet.
Use when: a theme exists on disk but isn't showing up in
themes_list_themes (not yet loaded).
Returns: list of file paths relative to the Home Assistant config
directory.
Inputs: no named parameters. Returns: result
themes_list_themesList themesARead-onlyIdempotent
List all Lovelace themes registered with the frontend.
Calls WS frontend/get_themes and returns Home Assistant's response
unchanged.
Use when: you need every theme's name plus which one is active before
switching or editing.
Returns: dict with themes (name to variable-map), default_theme,
and default_dark_theme.
Inputs: no named parameters. Returns: object
themes_reload_themesReload themes from diskAIdempotent
Reload theme files from the themes directory.
Calls service frontend.reload_themes, making Home Assistant re-read
every YAML file under <config>/themes/.
Use when: after themes_create_theme, themes_update_theme or
themes_delete_theme writes a file with reload=False, or after
editing a theme file outside nexus.
Returns: dict with status: 'reloaded'.
Inputs: no named parameters. Returns: object
themes_set_active_themeSet active themeAIdempotent
Set the active Lovelace frontend theme.
Calls service frontend.set_theme with name, and mode when it is
'light' or 'dark'; any other mode value is silently omitted from the
call.
Use when: switching which theme the frontend displays.
Returns: {"service": "frontend.set_theme", "changed_states": [...]} —
the states HA reports as changed by the call.
Limits: mode values other than 'light'/'dark' are dropped rather than
rejected.
Inputs: mode, name. Returns: object
themes_update_themeUpdate theme fileADestructive
Update an existing Lovelace theme file.
With merge=True (default), shallow-merges the given variables into
the existing top-level keys — a passed modes key replaces the whole
modes block rather than merging inside it; with merge=False,
replaces the entire variable set. Fails if the theme file doesn't
exist yet.
Use when: changing some or all variables on a theme that already
exists.
Not for: a theme that doesn't exist yet — use themes_create_theme.
Returns: dict with success, path, merged, and reloaded (present
when reload=True).
Errors: {"success": false, "error": "Theme '<name>' not found at <path>"} when the file doesn't exist; {"success": false, "error": "invalid_theme_name", "detail": ...} when name contains '/' or a
backslash, starts with '.', or is blank.
Inputs: name (required), variables (required), merge, reload. Returns: object
todo_add_itemAdd a todo list itemA
Add a new item to a todo list via the todo.add_item service.
Sends due_date or due_datetime depending on whether due_date
contains a time component ('T' or a space). Calling this twice with the
same item text creates two separate items with distinct uids.
Use when: adding a new entry to a todo list.
Not for: changing or completing an existing item — use
todo_update_item.
Returns: {"entity_id", "item", "result": ...} where result is the
service-call response.
Inputs: item (required), entity_id (required), due_date, description. Returns: object
todo_list_itemsList items on a todo listARead-onlyIdempotent
List items on a todo list, optionally filtered by status.
Calls WS todo/item/list and filters the returned items by status in
Python (HA's response shape for this command has varied between "items"
dicts and a bare list across versions, both are handled here).
Use when: reading a todo list's current items.
Not for: listing the todo entities themselves — use
todo_list_todo_lists.
Returns: list of item dicts as returned by HA (fields include uid,
summary/item text, status).
Inputs: entity_id (required), status. Returns: result
todo_list_todo_listsList todo list entitiesARead-onlyIdempotent
List all todo.* entities currently registered in HA.
Filters ha.get_states() for entity IDs starting with todo..
Use when: discovering which entity_id to pass to
todo_list_items/todo_add_item/todo_update_item/todo_remove_item.
Not for: the items within a list — use todo_list_items.
Returns: list of {"entity_id", "state", "friendly_name"} dicts, one
per todo.* entity.
Inputs: no named parameters. Returns: result
todo_remove_itemRemove a todo list itemADestructiveIdempotent
Remove an item from a todo list by its uid via the todo.remove_item service.
Use when: permanently deleting an item, e.g. after completing a task
you don't want to keep marked completed.
Not for: marking an item completed without deleting it — use
todo_update_item with status='completed'.
Returns: {"entity_id", "uid", "result": ...} where result is the
service-call response.
Inputs: uid (required), entity_id (required). Returns: object
todo_update_itemUpdate a todo list itemADestructive
Update a todo item's text and/or status via the todo.update_item service.
Maps item to the service's rename field. Only the fields you pass
(item/status) are sent, so whichever value is omitted is left
unchanged on HA's side.
Use when: renaming an item or marking it needs_action/completed.
Not for: adding a new item — use todo_add_item; not for removing one
— use todo_remove_item.
Returns: {"entity_id", "uid", "result": ...} where result is the
service-call response.
Inputs: uid (required), entity_id (required), item, status. Returns: object
voice_create_pipelineCreate an Assist pipelineA
Create a new Assist pipeline via WS assist_pipeline/pipeline/create.
Every parameter is forwarded as-is to HA; engine parameters are entity
IDs of the relevant provider (stt.*, tts.*, wake_word.*) rather
than free-form names. Calling this twice with the same name creates
two separate pipelines with distinct IDs, since HA assigns a new ID each
time.
Use when: setting up a new voice pipeline with a specific combination of
conversation/STT/TTS/wake-word engines.
Not for: changing an existing pipeline — use voice_update_pipeline.
Returns: the created pipeline dict, as returned by HA (includes its new
id).
Limits: engine parameters must already be installed entity IDs; discover
them with voice_list_stt_engines, voice_list_tts_engines,
voice_list_wake_word_engines and voice_list_conversation_agents
first.
Inputs: name (required), language, tts_voice, stt_engine, +7 more. Returns: object
voice_delete_pipelineDelete an Assist pipelineADestructiveIdempotent
Delete an Assist pipeline via WS assist_pipeline/pipeline/delete.
HA rejects deleting the pipeline currently marked preferred — call
voice_set_preferred_pipeline with a different id first in that case.
Use when: permanently removing a pipeline that is no longer needed.
Not for: the preferred pipeline without switching preference first, and
not for temporarily disabling a pipeline (HA has no such state).
Returns: {"deleted": true, "pipeline_id"} (Home Assistant itself
answers with no payload).
Inputs: pipeline_id (required). Returns: object
voice_get_pipelineGet an Assist pipelineARead-onlyIdempotent
Get a single Assist pipeline by id, or the preferred one if omitted.
Calls WS assist_pipeline/pipeline/get, passing pipeline_id only when
given.
Use when: you need one pipeline's full configuration (engines,
languages) rather than the whole list.
Not for: every pipeline at once — use voice_list_pipelines.
Returns: dict with the pipeline's engine/language fields, as returned by
HA.
Inputs: pipeline_id. Returns: object
voice_list_conversation_agentsList conversation agentsARead-onlyIdempotent
List conversation agents available for a pipeline's conversation step.
Calls WS conversation/agent/list and returns its payload unchanged.
Use when: discovering which conversation_engine value to pass to
voice_create_pipeline/voice_update_pipeline.
Not for: STT/TTS/wake-word engines — use voice_list_stt_engines/
voice_list_tts_engines/voice_list_wake_word_engines.
Returns: dict as returned by HA's conversation/agent/list WS command.
Inputs: no named parameters. Returns: object
voice_list_pipelinesList Assist pipelinesARead-onlyIdempotent
List all Assist pipelines plus the preferred pipeline id.
Calls WS assist_pipeline/pipeline/list and returns its payload
unchanged.
Use when: you need every configured pipeline, e.g. to pick one for
voice_set_preferred_pipeline or before editing one with
voice_update_pipeline.
Not for: a single pipeline's full detail — use voice_get_pipeline.
Returns: {"pipelines": [...], "preferred_pipeline": "<id>"}.
Inputs: no named parameters. Returns: object
voice_list_stt_enginesList speech-to-text enginesARead-onlyIdempotent
List installed speech-to-text engines as their stt.* entities.
Filters ha.get_states() for entity IDs starting with stt..
Use when: discovering which STT engine entity ID to pass to
voice_create_pipeline/voice_update_pipeline.
Not for: TTS or wake-word engines — use voice_list_tts_engines/
voice_list_wake_word_engines.
Returns: list of {"entity_id", "state", "attributes"} for each stt.*
entity.
Inputs: no named parameters. Returns: result
voice_list_tts_enginesList text-to-speech enginesARead-onlyIdempotent
List installed text-to-speech engines as their tts.* entities.
Filters ha.get_states() for entity IDs starting with tts..
Use when: discovering which TTS engine entity ID to pass to
voice_create_pipeline/voice_update_pipeline.
Not for: STT or wake-word engines — use voice_list_stt_engines/
voice_list_wake_word_engines.
Returns: list of {"entity_id", "state", "attributes"} for each tts.*
entity.
Inputs: no named parameters. Returns: result
voice_list_wake_word_enginesList wake-word enginesARead-onlyIdempotent
List installed wake-word detection engines as their wake_word.* entities.
Filters ha.get_states() for entity IDs starting with wake_word..
Use when: discovering which wake-word entity ID to pass to
voice_create_pipeline/voice_update_pipeline.
Not for: STT or TTS engines — use voice_list_stt_engines/
voice_list_tts_engines.
Returns: list of {"entity_id", "state", "attributes"} for each
wake_word.* entity.
Inputs: no named parameters. Returns: result
voice_set_preferred_pipelineSet the preferred Assist pipelineAIdempotent
Set the default Assist pipeline, used when no pipeline is specified.
Calls WS assist_pipeline/pipeline/set_preferred.
Use when: changing which pipeline Assist uses by default.
Not for: reading the current preference — use voice_list_pipelines,
whose response includes preferred_pipeline.
Returns: {"preferred_pipeline": pipeline_id} (Home Assistant itself
answers with no payload).
Inputs: pipeline_id (required). Returns: object
voice_update_pipelineUpdate an Assist pipelineADestructive
Update an existing Assist pipeline's fields via WS assist_pipeline/pipeline/update.
HA's WS API requires the full set of fields on every update call, so
this first fetches the current pipeline with WS
assist_pipeline/pipeline/get and fills in any parameter left as
None from that current state before sending the update — only the
parameters you actually pass are changed; the previous value of any
field you omit is lost from this call's perspective and replaced by
whatever assist_pipeline/pipeline/get returned for it.
Use when: changing one or more fields of an existing pipeline.
Not for: creating a new pipeline — use voice_create_pipeline.
Returns: the updated pipeline dict, as returned by HA.
Inputs: pipeline_id (required), name, language, tts_voice, +8 more. Returns: object
ws_call_serviceCall a service and return its responseADestructive
Call a Home Assistant action over WebSocket and return its response data.
Sends call_service with return_response=True always set, so actions
that support a response (e.g. weather.get_forecasts,
calendar.get_events) return it; actions without one (light.turn_on,
most control actions) fail with a validation error. domain/service
must match [A-Za-z0-9_]+ (ADR-0006 D3) or the call is refused first.
Refuses hassio.addon_stop/app_stop/addon_stdin/app_stdin against
nexus's own add-on (self_protection.is_own_addon); addon_restart/
app_restart stay allowed. Outright refuses the eight services
services_call_service gates behind confirm (ADR-0006 D5) — none
support a response (F1).
Use when: the action's response payload is needed, not just the changed
states.
Not for: a plain control action, or one of the eight guarded services —
use services_call_service for both.
Returns: raw WS result: {success, result: {context, response}} on
success, or a failure dict from HA; {"success": False} if no result
message arrives.
Errors: raises RuntimeError on a handshake timeout; {"error": "invalid_service_name"} for a malformed domain/service; {"error": "self_addon_hassio_service_blocked", "message": ...} for a blocked
hassio.* case; {"error": "guarded_service_refused", "message": ..., "use": "services_call_service"} for a guarded service.
Limits: blocks for up to timeout seconds (default 10), including the
initial handshake.
Inputs: domain (required), service (required), data, timeout. Returns: object
ws_get_configGet HA config via WebSocketARead-onlyIdempotent
Get Home Assistant's own configuration over WebSocket.
Sends get_config and waits up to timeout seconds for the matching
result message.
Use when: reading HA's location, unit system, version and component
list over the WebSocket transport.
Not for: the same data over HTTP — use history_get_ha_config.
Returns: HA's config dict from result.result (location, unit_system,
version, components, ...).
Errors: raises RuntimeError when the WebSocket handshake or the
result message does not arrive within timeout, or when a result
message arrives but is not successful.
Limits: blocks for up to timeout seconds (default 10), including the
initial handshake.
Inputs: timeout. Returns: object
ws_get_statesGet all entity states via WebSocketARead-onlyIdempotent
Get all entity states over the WebSocket API in one call.
Sends get_states and waits up to timeout seconds for the matching
result message; this can be faster than the HTTP /api/states
endpoint on large installs since it avoids per-entity HTTP overhead.
Use when: fetching every entity's state on a large installation.
Not for: a filtered or paginated state list — use
entities_list_entities.
Returns: the list of state dicts from HA's result.result.
Errors: raises RuntimeError when the WebSocket handshake or the
result message does not arrive within timeout, or when a result
message arrives but is not successful.
Limits: blocks for up to timeout seconds (default 10), including the
initial handshake.
Inputs: timeout. Returns: result
ws_listen_eventsListen for a HA event typeARead-onlyIdempotent
Passively wait for and collect events of one HA event type.
Subscribes to event_type via subscribe_events and collects up to
count events, returning early once that many arrive or whatever
arrived once timeout elapses.
Use when: observing any event type, e.g. integration or automation
events not tied to a single entity's state.
Not for: state changes on one specific entity — use
ws_listen_state_changes.
Returns: list of raw event payloads as HA sent them.
Errors: raises RuntimeError when the WebSocket handshake does not
complete within timeout.
Limits: blocks for up to timeout seconds, including the initial
handshake; collects at most count events.
Inputs: event_type (required), count, timeout. Returns: result
ws_listen_state_changesListen for one entity's state changesARead-onlyIdempotent
Passively wait for and collect state_changed events for one entity.
Subscribes to HA's state_changed event type, which has no server-side
per-entity filter, and counts only events matching entity_id toward
count, so unrelated entities' events do not displace the target's.
Returns early once count matching events arrive, or whatever arrived
once timeout elapses.
Use when: waiting for a specific entity to change state, e.g. to confirm
an action took effect.
Not for: any entity's events — use ws_listen_events with
event_type='state_changed'; a one-shot trigger condition — use
ws_subscribe_trigger.
Returns: list of dicts with entity_id, old_state, new_state,
last_changed.
Errors: raises RuntimeError when the WebSocket handshake does not
complete within timeout.
Limits: blocks for up to timeout seconds, including the initial
handshake; collects at most count events.
Inputs: entity_id (required), count, timeout. Returns: result
ws_render_templateRender a Jinja2 template via subscriptionARead-onlyIdempotent
Render a Jinja2 template through HA's WebSocket render_template subscription.
Sends render_template; HA acknowledges the subscription with a null
result, then streams the rendered value in a follow-up event. This
waits up to timeout seconds for that event and returns its result.
Use when: the WebSocket transport itself is specifically required.
Not for: a one-shot render — use services_render_template, a plain
HTTP call with no subscription semantics.
Returns: the rendered template value from the event's result field.
Errors: raises RuntimeError when the template itself errors (e.g. an
undefined variable), when the WebSocket handshake does not complete
within timeout, or when no event arrives within timeout.
Limits: blocks for up to timeout seconds (default 10), including the
initial handshake.
Inputs: template (required), timeout. Returns: result
ws_subscribe_triggerWait for a HA trigger to fireARead-onlyIdempotent
Passively wait for a Home Assistant trigger definition to fire once.
Sends subscribe_trigger with the given trigger and waits up to
timeout seconds for the matching event.
Use when: waiting for a specific trigger condition (state, time, numeric
state, ...) rather than polling.
Not for: raw state_changed events on one entity — use
ws_listen_state_changes.
Returns: the trigger's event context dict when it fires, or None if
timeout elapses first.
Errors: raises RuntimeError when the WebSocket handshake does not
complete within timeout.
Limits: blocks for up to timeout seconds, including the initial
handshake.
Inputs: trigger (required), timeout. Returns: result
zones_create_zoneCreate zone helperA
Create a zone as a UI helper (storage collection), not a YAML zone.
Calls WS zone/create with the given coordinates and radius; only
zones created this way can later be changed through
zones_update_zone or zones_delete_zone. zone.home (core config)
and YAML-defined zones live outside this storage collection and cannot
be created here.
Use when: adding a new geofence zone without editing configuration.yaml.
Returns: dict with status, name, and the raw WS result.
Errors: on failure, returns {"error": "<message>", "hint": "...", "name": ...} instead of raising.
Inputs: name (required), latitude (required), longitude (required), icon, +2 more. Returns: object
zones_delete_zoneDelete zone helperADestructiveIdempotent
Delete a zone helper.
Calls WS zone/delete; accepts either the bare helper id or the full
zone.<id> entity_id. Only works for zones created via
zones_create_zone — zone.home and YAML-defined zones reject this WS
command.
Use when: removing a UI-helper zone that is no longer needed.
Returns: dict with status, zone_id, and the raw WS result.
Errors: on failure, returns {"error": "<message>", "hint": "...", "zone_id": ...} instead of raising.
Inputs: zone_id (required). Returns: object
zones_get_user_locationGet person locationARead-onlyIdempotent
Get one person entity's current location.
Prefixes person_entity_id with person. if missing, then reads its
state and location attributes.
Use when: you need just one person's coordinates rather than scanning
a zone with zones_list_persons_in_zone.
Returns: dict with entity_id, state, latitude, longitude, gps_accuracy,
source.
Errors: {"error": "<message>", "entity_id": ...} if the person entity
does not exist.
Inputs: person_entity_id (required). Returns: object
zones_get_zoneGet zoneARead-onlyIdempotent
Get one zone entity's full state and attributes.
Prefixes entity_id with zone. if missing, then fetches it with
ha.get_state.
Use when: you need every attribute of a single zone rather than the
slimmed list from zones_list_zones.
Returns: the full HA state object for the zone (entity_id, state,
attributes).
Errors: {"error": "<message>", "entity_id": ...} if the zone entity
does not exist.
Inputs: entity_id (required). Returns: object
zones_list_persons_in_zoneList persons in zoneARead-onlyIdempotent
List person entities currently inside a given zone.
Reads the zone's own persons attribute (maintained by Home
Assistant's zone component); falls back to matching each person's
state string against the zone only when that attribute is entirely
absent, which also special-cases zone.home (Home Assistant always
reports "home" there regardless of the zone's friendly_name).
Use when: checking who is currently inside a specific zone. Returns: list of dicts (entity_id, state, friendly_name, latitude, longitude) for persons in the zone; empty list if the zone does not exist.
Inputs: zone_entity_id (required). Returns: result
zones_list_zonesList zonesARead-onlyIdempotent
List all zone entities with their common location attributes.
Reads all HA states and keeps zone.* entities, projecting each down
to entity_id, state, and any of latitude, longitude, radius,
friendly_name, passive and icon present in its attributes.
Use when: you need every zone's location and radius, e.g. before checking who is inside one. Returns: list of slimmed zone dicts as described above.
Inputs: no named parameters. Returns: result
zones_reload_zonesReload zones from YAMLAIdempotent
Reload zones defined in configuration.yaml.
Calls service zone.reload over HTTP, which makes Home Assistant
re-read YAML-defined zones without a full restart.
Use when: you edited zone YAML and want the change applied, or after
zones_create_zone reports that YAML zones aren't supported.
Returns: dict with status and the raw service-call result.
Errors: on failure, returns {"error": "<message>"} instead of
raising.
Inputs: no named parameters. Returns: object
zones_update_zoneUpdate zone helperADestructive
Update fields on an existing zone helper.
Calls WS zone/update; only the parameters you pass are sent, so
omitted fields keep their current value. Only works for zones created
via zones_create_zone (UI helpers) — zone.home and YAML-defined
zones reject this WS command.
Use when: adjusting a UI-helper zone's coordinates, radius or name.
Returns: dict with status, zone_id, and the raw WS result.
Errors: on failure (e.g. a YAML zone or zone.home), returns
{"error": "<message>", "hint": "...", "zone_id": ...} instead of
raising.
Inputs: entity_id (required), icon, name, radius, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 349 tools
The namespace prefixes plus extensive 'Not for: use X' cross-references do a lot of work to separate tools, but with 349 tools there is genuine overlap: entities_turn_on vs services_set_light_color vs helpers_set_input_boolean vs services_call_service, entities_list_entities vs ws_get_states vs snapshot_get_snapshot, areas_list_devices vs devices_list_devices vs search_search_devices. Descriptions help an agent choose correctly, but misselection risk is real at this scale.
Most tools follow a readable namespace_verb_noun convention, but there are noticeable deviations: redundant prefixes (git_git_status, hacs_get_hacs_repository) and off-pattern names (git_safe_write_with_checkpoint lacks a git_ namespace mount, entities_get_entity vs zones_get_zone naming styles). Still mostly predictable, but not clean enough for a 4.
349 tools is an extreme mismatch for any single server, far beyond even the 25+ 'heavy' threshold. Discovery aids (discover_tool_search, discover_list_namespaces) exist precisely because the surface is too large to hold in memory, which is itself a sign of a bloated catalogue.
Coverage is very broad — full CRUD for entities, areas, devices, labels, automations, scripts, scenes, zones, dashboards, add-ons, backups, HACS, plus discovery/search helpers. Minor gaps exist (e.g. Supervisor partial restore is not exposed), but an agent can accomplish nearly any HA workflow without a dead end.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.66151 npmMIT
- AlicenseAqualityCmaintenanceA self-hosted MCP server for Home Assistant that exposes full control over entity states, service calls, history, templates, and areas via local stdio, enabling AI assistants to manage your smart home.9108 npmMIT
- AlicenseAqualityCmaintenanceAn MCP server exposing 72 tools across 26 homelab services, enabling LLMs to monitor and manage infrastructure, media, storage, and networking with a single endpoint.16MIT
- AlicenseAqualityAmaintenanceA comprehensive MCP server that enables AI assistants to interact with Home Assistant, control smart home devices, query states, execute services, and manage automations via natural language.7798,673 PyPI8,030MIT