Read

HA NOVA Read

Scope

Read only:

• automation.list
• automation.read
• script.list
• script.read
• automation.trace
• script.trace

Not for helpers — use ha-nova:helper for helper list/read.

Multi-target scope is inventory-only:

• use skills/ha-nova/bulk-patterns.md for prefix / domain / area / label
• keep full YAML reads single-target only

No writes.

• MUST NOT issue POST, PUT, PATCH, or DELETE relay requests.
• MUST NOT call service endpoints or any other mutation path learned during the read flow.
• If the task becomes a config change, hand off to ha-nova:write with resolved IDs and current config.

Bootstrap (once per session)

Verify relay CLI: ha-nova relay health If this fails: ha-nova setup

Relay Contract

Use file-based relay requests:

1. Write final JSON payloads with the client's native file-writing tool. Do not create placeholder templates and patch them later with perl -0pi, sed -i, or similar rewrites.
2. Use ha-nova relay ws --data-file .
3. Use ha-nova relay core --method --path --body-file when a body is needed.
4. Use --jq-file for non-trivial filters and --out for large responses.

Flow

Listing automations / scripts

Use the compact entity registry (abbreviated keys: ei=entityid, en=name, ai=areaid):

Create `` with:

{"type":"config/entity_registry/list_for_display"}

Then run:

ha-nova relay ws --data-file  --jq-file 

Write `` with one of:

[.data.entities[] | select(.ei | startswith("automation.")) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:30]

[.data.entities[] | select(.ei | startswith("script.")) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:30]

For bulk inventory by prefix, domain, area, or label, reuse skills/ha-nova/bulk-patterns.md and return the compact table only. For area scope, use the search/related area projection rules, not compact-registry ai.

Keyword search

Use short keyword stems and always limit results.

ha-nova relay ws --data-file  --jq-file 

Write `` with:

[.data.entities[] | select(.ei | startswith("automation.")) | select((.ei + " " + (.en // "")) | test("KEYWORD";"i")) | {entity_id: .ei, name: .en, area_id: .ai}] | .[0:20]

If 0 results: try synonyms or shorter stems: test("kw1|kw2";"i").

For "automations in room X": stay inside read and follow the area-first search/related flow from skills/ha-nova/bulk-patterns.md.

Reading a single config

Resolve the config key via entity registry first; UI-created items often use numeric unique_id values.

1. Resolve unique_id:

• create ` with {"type":"config/entityregistry/get","entityid":"automation.{slug}"}`
• run ha-nova relay ws --data-file --out
• then run ha-nova relay jq -r --file '.data.unique_id' (POSIX example; on Windows/PowerShell pass the same filter with native argument quoting)
• write the final entity_id value directly into `; do not use placeholder tokens such as REPLACEENTITYID`
• for scripts: use script.{slug}

1. Fetch config into ``:

• ha-nova relay core --method GET --path /api/config/automation/config/{unique_id} --jq-file --out
• for scripts: /api/config/script/config/{unique_id}
• prefer copying skills/ha-nova/config-body-filter.jq to ``
• if you must recreate it, write `` with:

``jq if .ok then .data.body else error("relay error: \(.error.message // "unknown")") end ``

• if the contents differ, overwrite the same `` with the canonical line before the first config read; do not create alternate config-filter filenames
• POSIX heredocs shown elsewhere are examples only; on Windows/PowerShell preserve the same jq body with native file writing

1. Validate JSON:

• ha-nova relay jq --file -e --jq-file
• use type == "object"

1. For counts or follow-up transforms, use ha-nova relay jq --file with length or --jq-file .

Read the saved file with the native file-reading tool. Do not analyze configs from shell output.

Related entities

Find automations/scripts that use a specific entity:

Create `` with:

{"type":"search/related","item_type":"entity","item_id":"{entity_id}"}

Then run:

ha-nova relay ws --data-file 

If id is ambiguous, ask one clarifying question. Never use raw get_states.

Output Format

After reading a config, present:

**{Automation|Script}: {alias}**
- **ID:** {id}
- **Entities:** {list all entity_ids used in triggers, conditions, and actions}
- **Triggers:** {short description of each trigger}
- **Conditions:** {short description or "none"}
- **Actions:** {short description of each action, grouped by trigger if applicable}
- **Mode:** {single|restart|queued|parallel}

Then show the full YAML config:

alias: ...
triggers: ...
actions: ...

For list operations, use a compact table:

| Entity ID | Name | Area |
|-----------|------|------|

Never show raw JSON to the user.

Trace Debugging

For trace queries:

1. Resolve the unique_id (config key). item_id requires the unique_id, NOT the entity_id slug.

Create ` with the config/entity_registry/get request, then run: `text ha-nova relay ws --data-file --out ha-nova relay jq -r --file '.data.unique_id' `` The jq filter quoting above is a POSIX example. On Windows/PowerShell pass the same filter with native argument quoting.

1. List recent traces using the resolved unique_id:

Create ` with: `json {"type":"trace/list","domain":"automation","item_id":"{unique_id}"} ` `text ha-nova relay ws --data-file ` For scripts: "domain":"script"`.

1. For a detailed trace, save trace/get to ``:

Create ` with: `json {"type":"trace/get","domain":"automation","item_id":"{unique_id}","run_id":"{run_id}"} ` `text ha-nova relay ws --data-file --out ha-nova relay jq --file empty `` Read the file with your native file-reading tool.

1. Summarize timestamp, trigger, conditions, actions, and result.
2. If traces do not cover the relevant period, optionally check last_changed via /api/states/{entity_id}.
3. Before presenting conclusions, verify item_id in trace data matches the target's unique_id. see skills/ha-nova/SKILL.md → Claim-Evidence Binding.

Latency Policy

• no agent dispatch for simple reads
• no proactive /health preflight
• no exploratory retry loops without concrete failure

Safety

• never guess ids
• if multiple close matches, ask one selection question

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: markusleben
• Source: markusleben/ha-nova
• License: MIT
• Homepage: https://github.com/markusleben/ha-nova

Install and usage instructions live in the source repository linked above.