Home Assistant CLI

CLI for Home Assistant with token-efficient output and broad API coverage. Default TOON format reduces token usage versus pretty JSON and is suitable for both humans and LLM/agent tooling.

Project Status

Public release v2026.3.6 was published on March 6, 2026. See:

CHANGELOG for released and unreleased changes
Project History for pre-release implementation history and audits
Releasing Guide for publish workflow and CI/CD gates
Versioning scheme: YYYY.M.D for first release of the day, then YYYY.M.D-N

Features

Broad Home Assistant API Coverage - States, services, events, history, logbook, calendars, cameras, templates, and more
Device Control Commands - Dedicated light, switch, climate, cover, lock, fan commands with full parameter support
Token-Efficient Output - Default TOON format is compact and automation-friendly
Multiple Output Formats - TOON, JSON, JSON-compact, YAML, table, and markdown
Interactive Setup Wizard - Easy first-time configuration
Flexible Configuration - Environment variables, secure global config files (settings/auth/data), custom --config path, or CLI options
Read-Only Safety Mode - Block all state-changing API calls with --read-only or HASSIO_READONLY=true
GitHub Star Prompt - Setup/settings commands can prompt to star the repo via gh (when available and logged in)
Config Entry Management - List/filter/count/delete Home Assistant config entries with safety confirmation
LLM-Optimized Commands - Query language, batch operations, entity discovery
Capability Profiling for Agents - hassio capabilities probes runtime API support and caches results
Agent Execution Planning - hassio capabilities --agent-plan returns recommended and avoid command sets
Agent Execution Profile - hassio capabilities --agent-profile returns a stable execution profile and fast-path commands
One-Shot Agent Context - hassio capabilities --agent-context --redact-private returns summary + plan + profile safely
Fast Topology Snapshot - hassio summary returns domain/state counts for quick agent planning
Search Endpoint Fallback - Falls back to local entity-state search when /api/search is unavailable
Service Schema Intelligence - Supports modern object-style /api/services payloads with filter/flat/count modes
WebSocket API Coverage - Generic websocket/ws passthrough plus websocket status metadata
Supervisor API Coverage - Generic supervisor api passthrough + common shortcuts (addons, host, logs)
Full TypeScript Support - Complete type safety throughout
Comprehensive Testing - Large automated test suite with strong coverage

Installation

Using Bun (Recommended)

bun install -g @unbrained/homeassistant-cli

Using npx (No Installation)

npx @unbrained/homeassistant-cli --help

Using npm (Global Installation)

npm install -g @unbrained/homeassistant-cli

Using bunx (No Installation)

bunx @unbrained/homeassistant-cli --help

From Source

git clone https://github.com/unbraind/homeassistant-cli.git
cd homeassistant-cli
bun install
bun run build

Quick Start

Option 1: Interactive Setup (Recommended)

# Run the setup wizard
hassio settings wizard
hassio settings setup   # alias

# Agent/CI setup (no prompts)
hassio settings wizard --non-interactive \
  --ha-url "http://homeassistant.local:8123" \
  --ha-token "your-long-lived-access-token" \
  --skip-test

# Test connection
hassio status

Option 2: Environment Variables

export HASSIO_URL="http://homeassistant.local:8123"
export HASSIO_TOKEN="your-long-lived-access-token"

# Initialize from environment
hassio settings init

# Or use directly without saving
hassio status

Option 3: Manual Configuration

# Set configuration
hassio settings set --ha-url "http://192.168.1.100:8123" --ha-token "your-token"

# Set individual options
hassio settings set --default-format json
hassio settings set --default-timeout 60000
hassio settings set --read-only true

# Validate
hassio settings validate

Configuration Management

# View current configuration (token masked)
hassio settings get
hassio settings get --runtime-summary

# Enable or disable read-only safety mode
hassio settings set --read-only true
hassio settings set --read-only false

# View configuration with token (be careful!)
hassio settings get --show-token

# Include full runtime cache details (can be large)
hassio settings get --include-runtime

# List all configuration options
hassio settings list

# Show settings/auth/data file paths
hassio settings path

# Run diagnostics (API, output validation, supervisor probe)
hassio settings doctor

# Probe runtime capabilities for this specific HA instance
hassio capabilities --refresh
hassio capabilities --count
hassio capabilities --api-matrix
hassio capabilities --agent-plan
hassio capabilities --agent-profile
hassio capabilities --agent-context --redact-private --format json

# Reset all configuration
hassio settings reset --force

If gh is installed and authenticated, hassio settings ... commands will ask you to star unbraind/homeassistant-cli until it is starred.

Global Flags and Help

Global flags are supported for all commands:

-u, --url <url>
-t, --token <token>
-f, --format <format>
    --timeout <ms>
    --read-only
-c, --config <path>

Use hassio <command> --help to see command-specific options plus the global flag section.

Getting Your Token

Open Home Assistant in your browser
Click your profile (bottom left)
Scroll to "Long-Lived Access Tokens"
Click "Create Token"
Copy the token immediately (it won't be shown again)

Output Formats

TOON (Default) - Optimized for LLMs

Token-efficient format - ~40% fewer tokens than JSON:

states[2]{entity_id,state,last_changed,attributes}:
  light.living_room,on,2024-01-01T00:00:00Z,"{ ""brightness"":255}"
  switch.kitchen,off,2024-01-01T01:00:00Z,"{}"

Other Formats

hassio states --format json          # Pretty JSON
hassio states --format json-compact  # Minified JSON
hassio states --format yaml          # YAML
hassio states --format table         # ASCII table
hassio states --format markdown      # Markdown table

Core Commands

Basic Operations

# Check connection
hassio status

# Get entity states
hassio states                    # All entities
hassio states light.living_room  # Specific entity
hassio states --count            # Count only
hassio states --limit 25         # Limit list output

# Control devices
hassio call-service light turn_on -e light.living_room
hassio call-service light turn_on -e light.living_room -d '{"brightness":200}'

# Call services
hassio call-service climate set_temperature -e climate.living_room -d '{"temperature":22}'

# Explore service schema (agent-friendly)
hassio services --count
hassio services --domain light --flat

History & Logs

# Get history
hassio history -e sensor.temperature
hassio history -e sensor.temp1,sensor.temp2 -s "2024-01-01T00:00:00Z"

# View logs
hassio logbook
hassio error-log

Configuration

# Validate HA configuration
hassio check-config

# Render templates
hassio render-template "{{ states('sensor.temperature') }}"

LLM-Optimized Commands

Entity Discovery

# Discover all entities
hassio discover

# Get domain statistics
hassio discover --domains
hassio discover --domains --limit 10

# Find unavailable entities
hassio discover --unavailable

Entity Filtering

# Filter by domain
hassio entities -d light

# Filter by state
hassio entities -d light -s on

# Filter by pattern
hassio entities -p living_room

# Get count only
hassio entities --count

# Group by domain
hassio entities --domains

# Limit returned rows
hassio entities -d sensor --limit 25

Query Language

# Query with expressions
hassio query "domain:light state:on"
hassio query "domain:light state:on" --limit 20
hassio query "domain:sensor attributes:unit_of_measurement=°C"
hassio query "name:living" --summary

Batch Operations

# Turn off multiple lights
hassio batch -d light -s turn_off -e light.living_room,light.kitchen,light.bedroom

# Set brightness on multiple lights
hassio batch -d light -s turn_on -e light.living_room,light.kitchen --data '{"brightness":200}'

Deep Inspection

# One-shot environment summary for agents
hassio summary
hassio summary --top-states 15
hassio summary --full-states

# Inspect entity
hassio inspect light.living_room

# With history
hassio inspect sensor.temperature --history

Configuration

Priority Order

Configuration is loaded in this order (later overrides earlier):

Config files (~/.hassio-cli/settings.json, ~/.hassio-cli/auth.json, ~/.hassio-cli/data.json)
Environment variables
CLI options

Environment Variables

Variable	Description	Default
`HASSIO_URL`	Home Assistant URL	-
`HASSIO_TOKEN`	Long-lived access token	-
`HASSIO_FORMAT`	Output format	`toon`
`HASSIO_TIMEOUT`	Request timeout (ms)	`30000`
`HASSIO_READONLY`	Block write operations (`true`/`false`)	`false`
`HASSIO_CONFIG`	Custom config file path	`~/.hassio-cli/settings.json`

Settings Commands

# Interactive wizard
hassio settings wizard

# Initialize from environment
hassio settings init

# Validate configuration
hassio settings validate

# Set options
hassio settings set --url "http://..." --token "..."

# View configuration (token masked)
hassio settings get

# Show config path
hassio settings path

Settings files are written with 0600 permissions (owner read/write only).

Examples

Home Automation Workflows

# Turn on all lights in living room
hassio query "domain:light name:living state:off"
hassio batch -d light -s turn_on -e light.living_room_ceiling,light.living_room_lamp

# Check temperature sensors
hassio query "domain:sensor attributes:unit_of_measurement=°C" --summary
hassio query "domain:sensor attributes:unit_of_measurement=°C"

# Find and fix unavailable entities
hassio discover --unavailable

Calendar & Media

# List calendars
hassio calendars

# Get events
hassio calendar-events calendar.home \
    -s "2024-01-01T00:00:00Z" \
    -e "2024-01-31T23:59:59Z"

# Get camera snapshot
hassio camera camera.front_door -o snapshot.jpg

Voice Assistant & Conversation

# Ask a question
hassio ask "what time is it"

# Control devices via voice
hassio ask "turn on living room light"

# List conversation agents
hassio conversation --agents

# Multi-turn conversation
hassio conversation -t "turn on lights" -c "conv-123"

Text-to-Speech

# List TTS engines
hassio tts --engines

# Speak a message
hassio say "The front door is open" -p media_player.kitchen

# Use specific engine
hassio say "Welcome home" -p media_player.living_room -e tts.cloud

Search

# Search entities
hassio search "living room"
hassio search "living room" --limit 25

# Quick local search
hassio search "temp" --quick

# Search with filters
hassio search "sensor" -d sensor --count

WebSocket & Supervisor

# WebSocket connectivity/auth check
hassio websocket --connect-test

# WebSocket status metadata
hassio websocket status

# Generic WS command
hassio ws call -T get_states

# Target helper: resolve target selectors to concrete IDs
hassio ws target extract --area-id kitchen

# Target helper: get available services for a target
hassio ws target services --entity-id light.kitchen

# Target helper: resolve and fetch related registries
hassio ws target related --label-id lighting

# Capture WS events for 10s
hassio ws subscribe --event-type state_changed --wait-ms 10000 --max-events 20

# Supervisor shortcuts
hassio supervisor addons --list
hassio supervisor logs

# Full supervisor endpoint passthrough
hassio supervisor api -m GET -p /addons
hassio supervisor api -m GET --endpoint /addons

# Config entries (integration instances)
hassio config-entries --count
hassio config-entries --domain mqtt
hassio config-entries --delete <entry-id> --yes

If supervisor commands return 401 or 404, the CLI now reports actionable guidance:

401: token/permissions issue for supervisor access
404: installation does not expose supervisor endpoints (common on Core/Container)

Development

Note: This project uses Bun as the primary package manager and runtime.

# Install dependencies
bun install

# Run in dev mode
bun run dev -- status

# Run tests
bun run test
bun run test:coverage
bun run test:e2e:live   # Requires HASSIO_URL + HASSIO_TOKEN

# Build
bun run build

# Type check
bun run typecheck

# Lint
bun run lint

Documentation

API Reference - Complete command reference
Documentation Index - All documentation
LLM Integration - Agent/LLM guide

Security

Never commit tokens to version control
Config file is excluded from git via .gitignore
Token is masked in settings get output
Config file is written with 0600 permissions
Use environment variables for CI/CD pipelines

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
bun.lock		bun.lock
eslint.config.mjs		eslint.config.mjs
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Home Assistant CLI

Project Status

Features

Installation

Using Bun (Recommended)

Using npx (No Installation)

Using npm (Global Installation)

Using bunx (No Installation)

From Source

Quick Start

Option 1: Interactive Setup (Recommended)

Option 2: Environment Variables

Option 3: Manual Configuration

Configuration Management

Global Flags and Help

Getting Your Token

Output Formats

TOON (Default) - Optimized for LLMs

Other Formats

Core Commands

Basic Operations

History & Logs

Configuration

LLM-Optimized Commands

Entity Discovery

Entity Filtering

Query Language

Batch Operations

Deep Inspection

Configuration

Priority Order

Environment Variables

Settings Commands

Examples

Home Automation Workflows

Calendar & Media

Voice Assistant & Conversation

Text-to-Speech

Search

WebSocket & Supervisor

Development

Documentation

Security

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages