haz

A small CLI and Go library for the Home Assistant REST API.

Install

go install code.rbel.co/rubiojr/haz/cmd/haz@latest

Or build from source:

make build   # produces build/haz

Configuration

haz needs your Home Assistant base URL and a long-lived access token (create one from your Home Assistant profile page, under Long-lived access tokens). Provide them via flags or environment variables:

Flag	Env var
--url, -u	HAZ_URL, HASS_URL
--token, -t	HAZ_TOKEN, HASS_TOKEN

export HAZ_URL="https://ha.example.com:8123"
export HAZ_TOKEN="eyJ..."

notify

Send a push notification to one or more companion-app devices. The notification body is the trailing arguments.

# Basic notification
haz notify --device pixel "Backup done in 4m"

# With a title and high priority
haz notify -d pixel -T "Backup" -p high "12 GiB in 4m"

# Critical alert (overrides mute / Do-Not-Disturb)
haz notify -d pixel -p critical "Disk failing"

# Fan out to several devices
haz notify -d pixel -d phone "Dinner is ready"

# Target a raw notify service (e.g. a notify group) as-is
haz notify -s all_phones "Heads up"

# Discover the notify services your instance exposes
haz notify --list

--device maps to the notify.mobile_app_<device> service (the mobile_app_ prefix is added automatically). Use --service to target a service name verbatim.

Priority

Value	Behaviour
normal	Plain notification (default).
high	Android: wakes the device and delivers immediately.
critical	Overrides mute/DND. iOS needs the app's Critical Alerts permission.

cover

Control cover entities (blinds, shades, garage doors). Entity IDs may be given with or without the cover. prefix; it is added automatically.

# List covers, their state and current position
haz cover list

# Open one or more covers
haz cover open living_room
haz cover open cover.bedroom kitchen

# Close one or more covers
haz cover close living_room bedroom

# Set covers to a position percentage (0 = closed, 100 = open)
haz cover set --position 50 living_room
haz cover set -p 0 cover.bedroom kitchen

Positions mirror Home Assistant's cover.set_cover_position service. The list command shows each cover's current_position, or - for covers that don't report one.

presence

Show device presence (home/away) from device_tracker.* entities.

# Companion-app (mobile_app) devices only — the GPS-based trackers
haz presence list

# Every device_tracker (router, bluetooth, ping, ...)
haz presence list --all

By default only companion-app devices are listed, identified by their source_type: gps. Use --all/-a to include every device_tracker.

scheduler

Run declarative, condition-gated jobs on a cron schedule from a single always-on process. A job fires its do actions when its schedule elapses and every when condition holds.

haz scheduler validate    # parse & check the config
haz scheduler list        # show jobs and their next run time
haz scheduler run         # run the loop in the foreground

See docs/scheduler.md for the config format, schedule syntax, the available conditions and actions, and how to run it under systemd.

Go library

Everything the CLI does is available as a Go package:

go get code.rbel.co/rubiojr/haz

package main

import (
	"context"
	"log"
	"os"

	"code.rbel.co/rubiojr/haz"
)

func main() {
	ctx := context.Background()
	c := haz.New("https://ha.example.com:8123", os.Getenv("HAZ_TOKEN"))

	st, err := c.State(ctx, "cover.living_room")
	if err != nil {
		log.Fatal(err)
	}

	if st.State != "closed" {
		err = c.Notify(ctx, haz.Notification{
			Title:    "Blinds",
			Message:  "The living room blind is still open",
			Priority: haz.PriorityHigh,
		}, haz.MobileAppService("pixel"))
		if err != nil {
			log.Fatal(err)
		}
	}
}

Package	What it does
code.rbel.co/rubiojr/haz	REST client: entity states, service calls, notifications, covers, device trackers.
code.rbel.co/rubiojr/haz/scheduler	Runs YAML or Go-defined jobs on a cron schedule. Custom condition and action types can be registered.
code.rbel.co/rubiojr/haz/cron	Cron expression parser used by the scheduler.

The client package depends only on the standard library.