---
title: "Home Assistant CLI for AI agents (hassio) · Stefan Preu"
description: "hassio is an open-source Home Assistant CLI built for AI agents: compact TOON output, a read-only mode, capability probes and countable, bounded results."
url: https://preu.at/work/home-assistant-cli
updated: 2026-10-19
---

# Home Assistant CLI

a Home Assistant instance from the command line, shaped for agents: counts before payloads, a dry run before an action, and a switch that keeps every write out of reach.

- install: `npm install -g @unbrained/homeassistant-cli`
- version: 2026.8.10 · 10 Aug 2026
- commands: `hassio`, `homeassistant-cli`
- node: ≥ 22.19
- license: MIT
- source: [github.com/unbraind/homeassistant-cli](https://github.com/unbraind/homeassistant-cli)
- works with: [Home Assistant](https://www.home-assistant.io)

## what it’s for

hassio reads and controls Home Assistant over its REST and WebSocket APIs: states, services, history, logbook, calendars, cameras, templates, registries, automations, repairs and the supervisor. people can ask for a table or markdown; agents get compact TOON by default, or JSON and YAML.

in a smart home a wrong command switches something real, so coverage is the easy part. the harder part is letting an agent learn what this particular instance supports, read as little as it needs to plan, and change nothing while it explores.

## what it covers

states, services, events, history, logbook, calendars, cameras, templates, registries, WebSocket API, automation traces, repairs, media, supervisor.

## built for agents: walls around the effects

agents get room to look around. the boundaries sit where a command would change something in the house.

- **writes off on request.** with read-only mode on, every state-changing API call is blocked, for one command or the whole session. `export HASSIO_READONLY=true`
- **ask the instance first.** probes which APIs this instance actually answers, caches the result, and turns it into commands to prefer and commands to avoid. `hassio capabilities --agent-plan`
- **counts before payloads.** one call returns domain and state counts; most lists take --count and --limit, so planning doesn’t start with every entity in the house. `hassio summary`
- **rehearse an action.** a service call can run as a dry run with strict input checks, and automations can be validated without being executed. `hassio call-service light turn_on --area-id kitchen --dry-run --strict-input`
- **risky writes need a yes.** deleting config entries or acting on repairs takes an explicit --yes, and stays blocked in read-only mode. `hassio repairs ignore <domain> <issue-id> --yes`

## a first run

```sh
# # connect once; --non-interactive does the same for agents and CI
hassio settings wizard
hassio status
hassio summary
hassio query "domain:light state:on" --limit 20
```

commands from the project’s README; what they print depends on your server. checked against the README at [3afc186](https://github.com/unbraind/homeassistant-cli/blob/3afc186297fc20a3ac08d0528de98c6d9b28e45f/README.md) (npm 2026.8.10) · [npm](https://www.npmjs.com/package/@unbrained/homeassistant-cli)

## same rules, four services

each service CLI pairs compact, structured output with discovery an agent can read and writes that have to be asked for.

- [Jellyfin CLI](https://preu.at/work/jellyfin-cli): Jellyfin from the command line, built for agents.
- [SearXNG CLI](https://preu.at/work/searxng-cli): web search through your own SearXNG, built for agents.
- [Monica CLI](https://preu.at/work/monica-cli): your personal CRM from the command line, read-only by default.
- [PM CLI](https://preu.at/work/pm-cli): case study. project management is a context problem.

---

[preu.at](https://preu.at/) · Stefan Preu, agentic systems architect, based in austria · [every page for agents](https://preu.at/llms.txt) · this page in a browser: https://preu.at/work/home-assistant-cli