Home Assistant Control

Control and inspect Home Assistant via REST API for entities, states, services, scenes, scripts, and automations. Use when the user asks to turn devices on/o...

Security Scan

The skill's code, environment requirements, and runtime instructions are consistent with its stated purpose of controlling Home Assistant over its REST API.

Purpose & Capability

Name/description match the requested binaries and environment variables: bash, curl, jq and HA_TOKEN/HA_URL_* are exactly what a Home Assistant REST wrapper needs. Scripts operate against /api/... endpoints and provide entity discovery, safe action execution, and reference generation — all coherent with the stated purpose.

Instruction Scope

SKILL.md and the scripts confine their actions to Home Assistant API calls and local reference files. They validate paths begin with /api/, avoid arbitrary shell eval when loading env files, confirm entities before acting, and require explicit user confirmation for risky domains. No instructions ask the agent to read unrelated system files or send data to endpoints outside the configured HA base URL.

Install Mechanism

There is no install spec (instruction-only packaging). The repo includes shell scripts only; no external downloads or package installs are performed by the skill itself, minimizing install-time risk.

Credentials

Requested env vars (HA_TOKEN, HA_URL_PUBLIC, optional HA_URL_LOCAL/HA_URL/HA_ENV_FILE) are necessary and proportionate for talking to Home Assistant. The included ha_env.sh explicitly allowlists keys and parses env files without sourcing, limiting scope. The skill does require a long-lived token (which by design can control devices) — this is appropriate for the capability but carries the expected privilege.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges or modify other skills. It does not persist credentials into unrelated configs. Scripts write only to their own reference files (entities/naming-context) and temporary files during operation.

Assessment

This skill appears to do exactly what it says: call Home Assistant's REST API and provide helper scripts. Before installing, ensure you trust the skill source and the GitHub repo, and keep in mind that HA_TOKEN is powerful — anyone with it can control devices. Store HA_TOKEN in a private file with strict permissions (the skill supports an HA_ENV_FILE), prefer HTTPS HA_URL_PUBLIC for remote access, and review the scripts yourself if you want to be extra cautious. Run scripts/self_check.sh first to validate connectivity and environment. If you need least-privilege access, consider creating a token with limited permissions in Home Assistant rather than using a full-administration token.

Use Home Assistant REST API with a long-lived access token.

Requirements

For skill users (runtime)

• bash
• curl
• jq
• Home Assistant long-lived token (HA_TOKEN)
• Home Assistant public base URL (HA_URL_PUBLIC)

For skill maintainers (packaging/validation)

• python3
• pyyaml (required by skill-creator validator/packager scripts)

Required environment variables

• HA_TOKEN (required)
• HA_URL_PUBLIC (required; canonical target and fallback)
• Optional URL behavior:
  • if HA_URL_LOCAL is set (and no HA_URL override), local is tried first, then fallback to HA_URL_PUBLIC
  • HA_URL is an explicit override (if set, used directly)

Secrets handling (publish-safe)

• Keep keys/URLs in an external file, not in the skill folder.
• Set HA_ENV_FILE=/absolute/path/to/file.env when you want file-based secret loading.
• If HA_ENV_FILE is not set, scripts only use environment variables already present in the shell.
• scripts/ha_call.sh and scripts/self_check.sh load env file only when HA_ENV_FILE is provided.

Core workflow

1. Parse the user request into target entity/service + desired action.
2. Check references/naming-context.md for manual alias mappings first.
3. Verify entity exists before changing state.
4. Execute service call.
5. Re-check state and report outcome clearly.

Useful endpoints

• List states: GET /api/states
• Single state: GET /api/states/{entity_id}
• Call service: POST /api/services/{domain}/{service}

Headers:

• Authorization: Bearer $HA_TOKEN
• Content-Type: application/json

Scripts

• scripts/ha_env.sh — loads env file only when HA_ENV_FILE is explicitly set, using safe KEY=VALUE parsing (no source/eval).
• scripts/ha_call.sh — generic API caller for Home Assistant.
• scripts/fill_entities_md.sh — generate references/entities.md from GET /api/states.
  • Full map: ./scripts/fill_entities_md.sh
  • Filter domains: ./scripts/fill_entities_md.sh --domains light,switch,climate,sensor
• scripts/save_naming_context.sh — refresh references/naming-context.md for user-specific naming.
  • ./scripts/save_naming_context.sh
• scripts/ha_entity_find.sh — search entities by partial entity id or friendly name.
  • ./scripts/ha_entity_find.sh kitchen
  • ./scripts/ha_entity_find.sh temp --domains sensor,climate --limit 30
• scripts/ha_safe_action.sh — execute service actions with safety checks and risk confirmation.
  • ./scripts/ha_safe_action.sh light turn_on light.kitchen '{"brightness_pct":60}'
  • ./scripts/ha_safe_action.sh lock unlock lock.front_door --dry-run
  • Add --yes to bypass interactive confirmation for risky domains.
• scripts/self_check.sh — verify prerequisites and API connectivity/auth before running actions.
  • ./scripts/self_check.sh

Safety

• Confirm before high-impact actions (locks, alarms, garage/doors, heating shutdown).
• Do not print raw token values.
• If target entity is ambiguous, ask a follow-up question.
• Keep API paths scoped to Home Assistant endpoints only (/api/...).
• Use only HTTP(S) Home Assistant base URLs (HA_URL*), prefer HTTPS for public access.
• Avoid code execution when loading env files: parse key/value pairs, do not use source on untrusted paths.

Reference files

• references/entities.md — entity inventory
• references/naming-context.md — user alias memory for natural names (e.g. "living room light")

Publishing notes

• Keep examples generic (example_* IDs), no personal hostnames/tokens.
• Do not commit .env or any private env file with real tokens.
• Keep the skill focused: API workflow + reusable scripts + entity reference.