@truyman/hass

A Bun-built CLI for Home Assistant, bundled for Node.js and published to npm as @truyman/hass.

Install

npm install -g @truyman/hass

Quick Start

Create a long-lived access token in Home Assistant, then store it locally:

hass auth login

The default profile is stored at ${XDG_DATA_HOME:-~/.local/share}/home-assistant/auth.json.

You can always override the stored profile with flags or environment variables:

export HASS_SERVER=http://homeassistant.local:8123
export HASS_TOKEN=your-token

hass server info

Commands

hass auth

• login - Prompt for server URL and long-lived access token, validate, and store them.
• status - Show the active connection source and whether the credentials validate.
• logout - Remove the stored default profile.

hass server

• info
• config
• components
• directories
• health
• logs

info reads the authenticated /api/config endpoint and reports the instance URL, location, and version. Its URL uses the configured external URL, then internal URL, then the CLI connection URL. auth login and auth status use the same metadata.

hass states

• list [filter]
• get <entity>
• set <entity> [state]
• delete <entity>
• history [entities...]
• toggle <entities...>
• on <entities...>
• off <entities...>

Examples:

hass states list sensor\\.
hass states get light.kitchen
hass states set input_boolean.night_mode on
hass states history light.kitchen --since -2h --end 0m

hass services

• list [filter]
• call <domain.service>

Examples:

hass services list light\\.
hass services call light.turn_on --data entity_id=light.kitchen,brightness=180
hass services call weather.get_forecasts --json '{"entity_id":"weather.home"}' --return-response

hass events

• list
• fire <event>
• watch [event]

hass templates

• render [template]

Examples:

hass templates render '{{ states("sun.sun") }}'
hass templates render --file ./template.j2 --data entity_id=light.kitchen

hass areas

• list [filter]
• create <names...>
• delete <areas...>
• rename <area> <name>

hass devices

• list [filter]
• rename <device> <name>
• assign-area <area> [devices...]

hass entities

• list [filter]
• rename <entity> [newId] --name <name>
• assign-area <area> [entities...]

hass api

• get <path>
• post <path>
• ws <type>

Examples:

hass api get /api/states
hass api post /api/events/custom_event --data value=1
hass api ws config/area_registry/list

Global Options

• --server
• --token
• --timeout
• --insecure
• --output table|json|yaml|ndjson
• --columns NAME=path,...
• --sort-by path
• --no-headers
• --table-format plain|github|tsv
• --verbose

Connection precedence is:

1. CLI flags
2. Environment variables
3. Stored auth profile
4. Built-in defaults

Development

bun install
bun run check
bun test
bun run build

Tooling includes: Bun, @truyman/cli, oxfmt, oxlint, husky, lint-staged, and release-it.