Manage Energy Dashboard Preferences

Manage the Home Assistant Energy Dashboard preferences.

The Energy Dashboard configuration (grid/solar/battery/gas/water energy sources, individual device consumption sensors for electricity and water, cost tariffs) is stored in .storage/energy and not otherwise reachable via REST, services, or helper flows — this tool is the only way for agents to inspect or modify it.

WHEN TO USE:

• mode='get' / 'set': inspect or replace the full Energy Dashboard config. Use 'set' for bulk edits or anything touching multiple top-level keys at once.

• mode='add_device' / 'remove_device': add or remove a single device-consumption entry. The tool performs a fresh read-modify-write internally; the caller does NOT manage config_hash. Use water=True to target the water meter list instead of electricity.

• mode='add_source': append a single entry to energy_sources (grid, solar, battery, gas, or water). Same atomic read-modify-write semantics.

WHEN NOT TO USE:

• To create the underlying statistics themselves — they must already exist as HA entities before being referenced here; create them via the relevant integration's config flow first.

CAVEATS:

• energy/save_prefs has per-key FULL-REPLACE semantics. Passing {"device_consumption": [<one entry>]} deletes every other device the user had configured — silently, with no error. mode='set' requires a fresh config_hash for optimistic locking; convenience modes hide this entirely.

• config_hash accepts both a single str (full-blob lock) and a dict[_PrefsKey, str] keyed by top-level keys (per-key lock, taken from the config_hash_per_key field of the mode='get' response). The per-key form lets an agent submit only the top- level key it wants to change — set-equality between config keys and dict keys is enforced, and any key outside the canonical set (typo, etc.) on either side is rejected with VALIDATION_FAILED rather than silently dropped (so an empty submission cannot succeed as a no-op). A per-key submission still fully replaces that key's value as the save endpoint requires. Mismatch on any locked key returns RESOURCE_LOCKED with the offending keys in the response's top-level mismatched_keys (create_error_response flattens the context dict onto the response root).

• dry_run=True skips the hash check entirely for both forms; the per-key form is therefore silently accepted on dry runs even if its keys would mismatch the current state.

• A local shape check runs before every write; malformed payloads are rejected with a shape_errors list.

• After a successful write, the tool calls energy/validate and returns any residual issues as post_save_validation_errors in the response. These reflect semantic problems (missing stats, unit mismatches) that shape checks can't catch; the save persists regardless — correct the config and write again if needed.

• The underlying save endpoint is admin-only. Non-admin tokens will receive an authorization error from Home Assistant.

• Convenience modes are NOT idempotent: 'add_device' on an existing stat_consumption returns RESOURCE_ALREADY_EXISTS; 'remove_device' on a missing entry returns RESOURCE_NOT_FOUND. 'add_source' rejects duplicates by (type, stat_energy_from) for solar/battery/gas/water (RESOURCE_ALREADY_EXISTS); grid entries are appended without a duplicate check (multiple grid variants are legitimate, and grid has no single canonical uniqueness key) — the caller is responsible for de-duplicating grid sources.

• Convenience modes do NOT bypass the local shape check on dry_run: dry_run=True still raises RESOURCE_ALREADY_EXISTS (duplicate add_device / add_source), RESOURCE_NOT_FOUND (missing remove_device), or VALIDATION_FAILED (post-mutator shape error) when the proposed mutation is not applicable. The mutator and shape check both run before the dry-run short-circuit.