preu.at / work / home-assistant-cli

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.

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

● commands from the READMEhassio 2026.8.10
# connect once; --non-interactive does the same for agents and CIhassio settings wizardhassio statushassio summaryhassio 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 (npm 2026.8.10) · npm

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.