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

Current public release: v2026.8.6 (August 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
• Registry Intelligence - Compact entity discovery plus Core 2026.8 device migration topology and entity-ID naming policy
• WebSocket API Coverage - Generic passthrough plus typed targets, automation validation/runtime/traces, integration intelligence, frontend semantic catalogs, entity provenance, panels, heartbeat, signed paths, and voice-assistant exposure
• Bounded Media Discovery - Browse, search, and resolve media sources or players with read-only, agent-sized output
• Agent Diagnostics - Typed Repairs issue/fix flows and bounded related-resource topology search
• 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" \
  --config-read-only true \
  --skip-test \
  --format json-compact

# 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

1. Open Home Assistant in your browser
2. Click your profile (bottom left)
3. Scroll to "Long-Lived Access Tokens"
4. Click "Create Token"
5. 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: light.living_room
    state: on
    last_changed: "2024-01-01T00:00:00Z"
    attributes:
      brightness: 255
  - entity_id: switch.kitchen
    state: off
    last_changed: "2024-01-01T01:00:00Z"
    attributes:

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}'
hassio call-service light turn_on --area-id kitchen --dry-run --strict-input

# Execute a response-capable action (response policy defaults to auto)
hassio call-service climate set_temperature -e climate.living_room -d '{"temperature":22}'
hassio call-service weather get_forecasts -e weather.home -d '{"type":"daily"}'

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

call-service supports entity, device, area, floor, and label targets; REST or WebSocket transport; file-backed data; and auto|always|never response policy. It always emits the same typed action envelope for parser-safe automation.

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):

1. Config files (~/.hassio-cli/settings.json, ~/.hassio-cli/auth.json, ~/.hassio-cli/data.json)
2. Environment variables
3. 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

# Inspect the media tree without loading private media rows
hassio media browse --count

# Browse or search with an explicit agent context bound
hassio media browse --limit 20
hassio media search "ambient" --media-class artist,album --limit 10

# Search a player that advertises SEARCH_MEDIA support
hassio media search "news" --entity-id media_player.living_room --count

# Confirm a media item resolves without returning its signed URL
hassio media resolve "media-source://provider/item" --metadata-only

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

Compact Registry Discovery

# Count enabled registry entries before fetching context
hassio registries --display --count

# Lowest-token compact entity metadata
hassio registries --display --domain light --limit 25

# Descriptive keys for JSON pipelines
hassio registries --decode-display --area-id kitchen --limit 25 --format json-compact

# Core 2026.8 device migration and cross-integration identity topology
hassio registries composite-splits --count
hassio registries linked-devices <device-id> --limit 25

# Preview automatic IDs, then inspect the global naming policy
hassio registries automatic-entity-ids light.kitchen sensor.temperature
hassio registries entity-id-settings get

# Admin-only mutation; blocked locally by --read-only/HASSIO_READONLY=true
hassio registries entity-id-settings update --parts floor,area,device,entity

The composite-split, linked-device, and naming-settings commands require Home Assistant Core 2026.8.1 or newer. Older servers report unknown_command; use hassio capabilities --api-matrix to detect support before planning a workflow.

WebSocket & Supervisor

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

# WebSocket status metadata
hassio websocket status

# Typed session discovery and liveness
hassio ws panels
hassio ws ping

# Filter explicit Assist exposure without fetching an unbounded payload
hassio ws exposure list --assistant conversation --limit 20

# Create a short-lived path; treat the output as a credential
hassio ws sign-path --path /api/states --expires 20

# Generic WS command
hassio ws call -T get_states

# Target helper: resolve target selectors to concrete IDs
hassio ws target extract --area-id kitchen
hassio ws target extract --device-id <id> --include-secondary

# Discover automation primitives that apply to a target
hassio ws target triggers --entity-id light.kitchen
hassio ws target conditions --entity-id light.kitchen
hassio ws target services --entity-id light.kitchen
hassio ws target services --entity-id group.downstairs --no-expand-group

# Validate automation definitions without executing them
hassio ws validate-config --action '[{"action":"light.turn_on","target":{"entity_id":"light.kitchen"}}]'
hassio ws validate-config --file automation.json

# Evaluate and observe condition truth without executing actions
hassio ws automation-runtime test-condition --file automation.json
hassio ws automation-runtime observe-condition --file automation.json --wait-ms 10000 --max-events 3

# Execute the same file's action sequence after approval (blocked by --read-only)
hassio ws automation-runtime execute-sequence --file automation.json

# Diagnose stored automation/script executions without changing runtime state
hassio ws traces list --domain automation --limit 20
hassio ws traces contexts --count
hassio ws traces get --domain automation --item-id <id> --run-id <run-id>

# 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

# Capture a compact snapshot plus bounded state deltas without full event envelopes
hassio ws observe-entities --domain light --wait-ms 10000 --max-events 20

# Discover current purpose-specific automation platform schemas
hassio ws automation-platforms --kind all

# Observe integrations that remain pending during Home Assistant bootstrap
hassio ws bootstrap-integrations --wait-ms 10000 --max-events 5

# Inspect loaded integrations without raw WebSocket payload knowledge
hassio ws integrations list --limit 20
hassio ws integrations get mqtt
hassio ws integrations setup --count
hassio ws integrations descriptions --domain mqtt
hassio ws integrations wait homeassistant

# Map entity ownership and generate Home Assistant-compatible slugs
hassio ws entity-sources --domain light --limit 20
hassio ws slugify "Kitchen Ceiling Light"

# Discover frontend version and bounded semantic/localization catalogs
hassio ws frontend version
hassio ws frontend themes --count
hassio ws frontend icons --category services --integration light --limit 50
hassio ws frontend translations --language en --category services --integration light --count

# Observe automation triggers without firing them (admin only)
hassio ws subscribe-trigger \
  --trigger '{"trigger":"event","event_type":"doorbell"}' \
  --wait-ms 30000 --max-events 5

# 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

Repairs & Related Resources

# Count active repair issues without exposing instance identifiers
hassio repairs list --count

# Inspect a bounded severity slice or one issue's integration-provided data
hassio repairs list --severity critical --limit 20
hassio repairs show <domain> <issue-id>

# Explicitly confirmed writes; blocked by --read-only / HASSIO_READONLY=true
hassio repairs ignore <domain> <issue-id> --yes
hassio repairs ignore <domain> <issue-id> --restore --yes
hassio repairs fix start <handler> <issue-id> --yes
hassio repairs fix status <flow-id>
hassio repairs fix submit <flow-id> --data '{"confirm":true}' --yes

# Traverse Home Assistant's resource topology with per-type bounds
hassio related entity light.kitchen --limit 20
hassio related area kitchen --result-type automation --count

Repair and topology identifiers are private instance data. Prefer --count for planning, use small limits, and do not persist raw results in logs or prompts.

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

The release contract requires 100% statements, branches, functions, and lines, 100% source-file docstrings, strict erasable TypeScript, PM integrity, duplicate-code and file-size ratchets, dependency/security scans, and package smoke tests. See Quality and Security Gates for the exact local commands and hosted contexts.

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