Home Assistant CLI

Use this skill when the user wants to interact with Home Assistant through the upstream hass-cli command-line tool from home-assistant-ecosystem/home-assistant-cli.

When To Use

Use this skill for requests involving hass-cli, Home Assistant CLI, Home Assistant command-line automation, entities, states, services, devices, areas, events, templates, raw API calls, or Home Assistant Operating System supervisor/core commands.

Do not use this skill for the separate ha command-line tool unless the user specifically asks to use hass-cli ha ... commands.

Safety

• Never print or expose HASS_TOKEN, HASS_SUPERVISOR_TOKEN, HASS_PASSWORD, long-lived access tokens, or API keys.
• Do not read, print, dump, or expose environment variables. Avoid commands such as env, printenv, export, set, declare, or echo $HASS_TOKEN. Never inspect token values directly.
• When checking Home Assistant access, run hass-cli commands and report success or sanitized errors. If authentication appears missing, ask the user to confirm that HASS_SERVER, HASS_TOKEN, or HASS_SUPERVISOR_TOKEN are set without revealing their values.
• Prefer read-only discovery commands before making changes.
• Ask for confirmation before commands that change state, call services, update/delete areas, assign devices, create backups, update Home Assistant Core, or use raw endpoints and WebSocket commands that mutate data. Read-only raw get and raw ws requests can be used for inspection.
• Avoid --insecure unless the user explicitly accepts connecting with ignored TLS certificate validation.
• Use --output=json or --output=yaml for data that will be parsed or summarized.

Setup Checks

1. Check whether hass-cli is installed with hass-cli --version.
2. If missing, suggest one upstream-supported install method: pip install homeassistant-cli, brew install homeassistant-cli, dnf install home-assistant-cli, NixOS package, or Docker.
3. Confirm connection configuration without revealing secrets. hass-cli uses HASS_SERVER and HASS_TOKEN, or --server and --token per command.
4. For Home Assistant Operating System hass-cli ha ... commands, verify that supervisor access is available through HASS_SUPERVISOR_TOKEN or --supervisor-token.
5. Use hass-cli system info or hass-cli raw get /api/ for a read-only connectivity check when access is needed.

Command Syntax Is Live

The installed CLI is the source of truth. Do not infer command names, option names, option placement, or argument formats from memory, examples, another CLI, or a sibling command.

Before composing a command:

1. Run hass-cli --version and note the installed version.
2. Run hass-cli --help to confirm the command group exists.
3. Run hass-cli GROUP --help to confirm the subcommand exists.
4. Run hass-cli GROUP COMMAND --help immediately before using that command.
5. Use only arguments and options shown by the exact command help. Do not transfer options between commands without verifying them.

Global options such as --output, --columns, --sort-by, and --no-headers normally belong before the command group, for example hass-cli --output=json state list. If the command's help shows a different placement, follow that help.

If the CLI reports an unknown command, option, or argument, stop and inspect the relevant help output. Do not retry by guessing a spelling, changing option placement, or substituting a command from another CLI. Report the installed version and sanitized error if the supported syntax is still unclear.

Use the installed hass-cli executable directly. Do not import homeassistant_cli.cli.run, replace sys.argv, or hardcode a package-manager path unless the executable has a confirmed runtime compatibility failure.

Common Commands

Read-only commands:

hass-cli config release
hass-cli state list
hass-cli state get light.example
hass-cli service list
hass-cli device list
hass-cli area list
hass-cli event watch
hass-cli ha core info
hass-cli ha supervisor info

State and service changes:

hass-cli service call homeassistant.toggle --arguments entity_id=light.office_light
hass-cli service call backup.create
hass-cli state edit sensor.test --json='{ "state": "off" }'

service call invokes Home Assistant behavior and is the normal way to control a physical device. state edit writes an entity state representation and is not a replacement for turning a light, switch, climate device, or other physical entity on or off. Use state edit only when the user explicitly needs to alter an entity state and the exact command help confirms the intended behavior.

Formatting and filtering

hass-cli --output=json state get light.example
hass-cli --output=yaml service list homeassistant.toggle
hass-cli --no-headers state list
hass-cli --columns=ENTITY=entity_id,STATE=state state list light
hass-cli --sort-by last_changed state history --since 50m light.kitchen

Templates and raw API

hass-cli template motionlight.yaml.j2 motiondata.yaml
hass-cli template --local lovelace-template.yaml
hass-cli raw get /api/

The raw ws command sends a Home Assistant WebSocket request. Confirm its syntax with hass-cli raw ws --help before use. For example, inspecting the Lovelace configuration and selecting PS5 cards is read-only:

hass-cli --output=json raw ws lovelace/config \
  --json='{"url_path":"lovelace","force":false}' |
  jq '[.result.views[].sections[]?.cards[]?
       | select(.type == "custom:ps5-card")
       | {type, name, power_entity, activity_entity}]'

Treat other WebSocket types according to their actual effect. A WebSocket transport is not inherently a state change, but a command that creates, updates, or deletes Home Assistant data requires confirmation and post-change verification.

Runtime Compatibility Fallbacks

Use the installed hass-cli executable directly for normal commands. Do not wrap every invocation in Python or import homeassistant_cli.cli.run merely to parse output or run a test; use --output=json and tools such as jq instead.

If the executable fails with an asyncio error such as There is no current event loop in thread, capture the installed hass-cli --version, Python version, and sanitized traceback before trying a workaround. Confirm that the failure is caused by the known Python 3.14 incompatibility.

Prefer these options in order:

1. Upgrade homeassistant-cli to a release containing the upstream fix.
2. If no fixed release is available, use a supported Python runtime such as Python 3.13 in an isolated environment.
3. If the user explicitly approves a local patch, inspect the installed homeassistant_cli/remote.py and compare it with upstream fix #457 before editing. Patch only the wsapi implementation, replacing asyncio.get_event_loop() plus run_until_complete(fetcher()) with asyncio.run(fetcher()). Tell the user that package upgrades may overwrite the patch and verify the executable directly afterward.

The upstream fix is tracked in home-assistant-ecosystem/home-assistant-cli#457. Do not use a Python wrapper or local patch to bypass authentication, TLS, host validation, or confirmation requirements. Keep any compatibility workaround limited to the failing CLI.

Workflow

1. Identify whether the task is inspection, automation, configuration, or administration.
2. Check the installed version and obtain help for the exact command path before writing the command.
3. Start with read-only discovery such as state list, service list, device list, area list, or entity/integration discovery.
4. Use exact entity IDs, service names, device names, area names, and command options from discovery and help output rather than guessing.
5. Choose parseable output with --output=json or --output=yaml when consuming results programmatically, and verify that the exact command accepts the selected global option.
6. For physical device control, identify the service from service list and use service call; do not substitute state edit.
7. Before making changes, show the exact command and get confirmation unless the user has already explicitly requested that action.
8. After changes, verify with a read-only command such as state get, area list, device list, or ha core info.

Command Groups

• config: configuration and release information.
• state: list, inspect, edit, and view history for entity states.
• service: list and call services.
• area: list, create, and delete areas.
• device: list devices and assign devices to areas.
• entity: inspect entity registry data.
• event: watch Home Assistant events.
• integration: inspect and operate on config entries.
• map: open the Home Assistant location or entity location on a map.
• template: render templates on the server or locally.
• raw: call the raw REST and WebSocket APIs; classify requests as read-only or mutating.
• ha: Home Assistant Operating System commands for Supervisor/Core operations; requires supervisor token access.

Notes

• hass-cli defaults to table or auto output; use --output=json, --output=yaml, or --output=ndjson when reliability matters.
• --columns uses JSONPath expressions such as ENTITY=entity_id and NAME=attributes.friendly_name.
• --sort-by sorts by underlying JSON/YAML properties, not displayed table column names.
• Autocompletion can be enabled with _HASS_CLI_COMPLETE for bash, zsh, or fish, but do not modify shell startup files unless the user asks.