Get Dashboard
ha_config_get_dashboardList Home Assistant dashboards, retrieve Lovelace configs for a whole dashboard or a single view, and locate cards by entity, type, or heading with exact paths for targeted updates.
Instructions
Get dashboard info - list all dashboards, get config, or search for cards.
MODE 1 — List: list_only=True Lists every dashboard's metadata (url_path, title, icon), storage and YAML alike (metadata only — bodies are never included here).
MODE 2 — Search: any of entity_id / card_type / heading provided
Finds cards, badges, and header cards matching the criteria, including
cards nested inside stacks, grids, conditional cards, button-card
custom_fields, and state-switch states. Each match carries a
python_path and a jq_path that locate the card for nested as well as
top-level cards. The python_path is a Python subscript chain to be
appended after config — e.g.
python_transform=f'config{m["python_path"]}["icon"] = "mdi:x"' (it is
NOT valid on its own without the config prefix). jq_path is the same
location in jq dot-notation.
Multiple criteria are AND-ed. Always fetches fresh config (force=True).
Search covers cards/card/custom_fields/states containers up to a depth
bound; if the dashboard carries a non-traversed child-bearing shape
(e.g. picture-elements elements), the result carries a warnings
entry naming where, so its hidden content is not mistaken for absent.
Strategy dashboards are not searchable (no explicit cards).
MODE 3 — Get: Active when list_only=False and no search parameters are provided.
Returns the full Lovelace dashboard config, defaulting to the
main dashboard if url_path is omitted.
Pass view_path=<views[].path> to return ONLY that view: the response
then carries view + view_index instead of config, keeping the
payload small on multi-view dashboards. config_hash still covers
the FULL config, so a follow-up
ha_config_set_dashboard(python_transform=...) addressing
config['views'][view_index] validates unchanged. An unknown
view_path errors and lists the available view paths.
include_screenshot=True also returns rendered image(s) of the
dashboard (beta feature); when you only need the render and not
the config, use the dedicated ha_get_dashboard_screenshot tool
instead.
MODE 4 — Search all: mode="search" with query=
Answers "which dashboards contain this entity/card" by walking every
storage-mode dashboard's views/cards/sections for the query substring.
Each match names the url_path, view, card_path, card_type, and the
matched field/value. Takes precedence over the other modes (list_only /
entity_id / card_type / heading are ignored when mode="search").
YAML-mode dashboards are never searched on either path — the component
walk skips them in-process and the component-less legacy walk skips any
row tagged mode="yaml" — because HA resolves !secret when loading a
YAML Lovelace config, so searching one could surface resolved secrets.
On installs without the ha_mcp_tools component, the default (unnamed)
dashboard is also not searched — only dashboards with a url_path are.
Return a stable config_hash (Get and Search modes only; not present in list_only mode) across consecutive reads of an unchanged config — compute_config_hash documents the underlying contract.
EXAMPLES:
List all dashboards: ha_config_get_dashboard(list_only=True)
Get default dashboard: ha_config_get_dashboard(url_path="default")
Get custom dashboard: ha_config_get_dashboard(url_path="lovelace-mobile")
Get one view only: ha_config_get_dashboard(url_path="lovelace-mobile", view_path="office")
Force reload: ha_config_get_dashboard(url_path="lovelace-home", force_reload=True)
Find cards by entity: ha_config_get_dashboard(url_path="my-dash", entity_id="light.living_room")
Find by wildcard: ha_config_get_dashboard(url_path="my-dash", entity_id="sensor.temperature_*")
Find by type: ha_config_get_dashboard(url_path="my-dash", card_type="tile")
Find heading: ha_config_get_dashboard(url_path="my-dash", heading="Climate", card_type="heading")
SEARCH WORKFLOW EXAMPLE:
find = ha_config_get_dashboard(url_path="my-dash", entity_id="light.bedroom")
ha_config_set_dashboard( url_path="my-dash", config_hash=find["config_hash"], python_transform=f'config{find["matches"][0]["python_path"]}["icon"] = "mdi:lamp"' )
Note: YAML-mode dashboards (defined in configuration.yaml) are not included in list.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Set to 'search' for a CROSS-dashboard search: which dashboards contain a given entity_id or text (requires query). Leave unset for the default list/get/single-dashboard-search behavior selected by list_only / entity_id / card_type / heading. | |
| query | No | With mode='search': the entity_id or substring to find across all storage-mode dashboards. Ignored otherwise. | |
| heading | No | Find cards by heading/title text (case-insensitive partial match). When provided, activates search mode. | |
| url_path | No | Dashboard URL path (e.g., 'lovelace-home'). Use 'default' for default dashboard. If omitted with list_only=True, lists all dashboards. | |
| card_type | No | Find cards by type, e.g. 'tile', 'button', 'heading'. When provided, activates search mode. | |
| entity_id | No | Find cards by entity ID. Supports wildcards, e.g. 'sensor.temperature_*'. Matches cards with this entity in 'entity' or 'entities' field, view-level badges, and header cards. When provided, activates search mode (returns matches, not full config). | |
| list_only | No | If True, list all dashboards instead of getting config. When True, url_path is ignored. | |
| view_path | No | Get mode: return ONLY the view whose Lovelace views[].path matches (response carries 'view' + 'view_index' instead of the full 'config') — use this to keep multi-view dashboards from blowing up the response when you only need one view. Does not require any beta feature. With include_screenshot, also selects the view to render. Ignored in list/search mode. Omit for the full config. | |
| force_reload | No | Force reload from storage (bypass cache). Not applicable in search mode (search always uses force=True for fresh results). | |
| include_config | No | In search mode: include each matched card's own configuration object in results (increases output size). Note that a matched container card's config contains its descendants, which are themselves separate matches with their own config, so deeply-nested stacks multiply the payload — keep the default (False) unless you need the bodies. Does not affect whether the full dashboard config is returned — search mode always returns matches only, not the full dashboard. Config bodies are surfaced only for dashboards provably in storage mode; for a YAML or unconfirmed dashboard the bodies are withheld (they may carry resolved !secret values) and the response says so, with match locations still reported. Ignored outside search mode. | |
| include_screenshot | No | Get mode only: also return rendered image(s) of the dashboard for visual verification. Requires the 'dashboard screenshot' beta feature + engine add-on/sidecar. If the feature is disabled the config is returned with a warning; if the engine is configured but the render fails, the call errors (the screenshot is the requested payload). Ignored in list/search mode. When you already have the config and only need the render, use the dedicated ha_get_dashboard_screenshot tool (registered when the same beta feature is on) — it returns images without echoing the config. |