Safe household actions, offline memory, and evidence-backed answers on top of the full Home Assistant control surface.
Match the useful breadth of hass-cli and ha-mcp, then add preview/apply/verify modes, routine debugging, reference linting, health hotspots, and household exception checks. The same typed Go command tree works for people, scripts, agents, and MCP clients.
Authentication
Set HASS_SERVER to your Home Assistant instance URL and HASS_TOKEN to a Long-Lived Access Token created from your Home Assistant profile. The CLI sends the token as a bearer credential to REST and as an access token during WebSocket authentication; it never prints or syncs the token.
Quick Start
# Validate configuration and see the exact server/auth prerequisites without making a request.
home-assistant-pp-cli doctor --dry-run
# Create a local household snapshot for offline search and compound commands.
home-assistant-pp-cli sync --resources states,devices,areas --full
# Get a context-efficient answer to the most common whole-home question.
home-assistant-pp-cli house check --agent --select category,entity_id,friendly_name,area,state,severity
# Preview every resolved target and expected action before changing the home.
home-assistant-pp-cli mode run movie-night --dry-run --agent
Unique Features
These capabilities aren't available in any other tool for this API.
Safe household action
-
mode run — Preview a scene or script, run it, and verify every resulting entity state.
Use this when an agent must change several household devices safely instead of firing an unverified scene or service call.
home-assistant-pp-cli mode run movie-night --agent
Household awareness
-
house check — See open windows, unlocked locks, lights left on, low batteries, and unavailable safety devices in one answer.
Use this for immediate household safety and comfort questions that span several entity domains.
home-assistant-pp-cli house check --agent --select category,entity_id,friendly_name,area,state,severity
-
house recap — Review factual household activity, routine failures, presence changes, openings, and unavailable time for a recent period.
Use this for a compact, evidence-based household summary that remains useful offline.
home-assistant-pp-cli house recap --since 7d --agent
Routine intelligence
-
routine why — Reconstruct why an automation or script failed from traces, state changes, logbook entries, and errors.
Use this when an agent needs evidence for one failed routine instead of dumping an opaque trace.
home-assistant-pp-cli routine why automation.movie_night --agent
-
routine lint — Find missing entities, unavailable services, disabled dependencies, ambiguous names, and stale routine references.
Use this before configuration changes or upgrades to catch deterministic breakage before Home Assistant executes a routine.
home-assistant-pp-cli routine lint --agent
-
routine impact — See every automation, script, scene, helper, and service target affected by changing one entity or routine.
Use this before renaming, disabling, or removing something that other household routines may depend on.
home-assistant-pp-cli routine impact light.living_room --agent
Self-hosted maintenance
-
health hotspots — Group recurring unavailable, stale, low-battery, and disconnecting entities into device, room, integration, and radio hotspots.
Use this when many entity symptoms may share one failing device, integration, room, or radio network.
home-assistant-pp-cli health hotspots --agent
-
energy standby — Find devices drawing persistent power during explicit periods when related household states show inactivity.
Use this to turn household energy history into a short list of actionable standby loads.
home-assistant-pp-cli energy standby --since 7d --agent
Recipes
Check the home
home-assistant-pp-cli house check --agent --select category,entity_id,friendly_name,area,state,severity
Narrow the whole-home exception report to the fields an agent needs to decide what to do next.
Preview movie night
home-assistant-pp-cli mode run movie-night --dry-run --agent
Resolve the household mode and inspect every action without changing any device.
Explain a failed routine
home-assistant-pp-cli routine why automation.movie_night --agent
Join the relevant trace, state, logbook, and error evidence into one incident timeline.
Review maintenance hotspots
home-assistant-pp-cli health hotspots --agent
Group recurring symptoms into the devices, integrations, areas, or radios most likely to need attention.
Usage
Run home-assistant-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
HOME_ASSISTANT_CONFIG_DIR, HOME_ASSISTANT_DATA_DIR, HOME_ASSISTANT_STATE_DIR, or HOME_ASSISTANT_CACHE_DIR
--home <dir> for this invocationHOME_ASSISTANT_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export HOME_ASSISTANT_HOME=/srv/home-assistant
home-assistant-pp-cli doctor
Under HOME_ASSISTANT_HOME=/srv/home-assistant, the four dirs resolve to /srv/home-assistant/config, /srv/home-assistant/data, /srv/home-assistant/state, and /srv/home-assistant/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"home-assistant": {
"command": "home-assistant-pp-mcp",
"env": {
"HOME_ASSISTANT_HOME": "/srv/home-assistant"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as HOME_ASSISTANT_DATA_DIR overrides an explicit --home for that kind. Use HOME_ASSISTANT_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting HOME_ASSISTANT_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run home-assistant-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
calendars
Manage calendars
home-assistant-pp-cli calendars list - List calendarshome-assistant-pp-cli calendars list-events - List calendar events
components
Manage components
home-assistant-pp-cli components - List loaded components
config
Manage config
home-assistant-pp-cli config get-system-info - Get Home Assistant configuration and versionhome-assistant-pp-cli config validate - Validate Home Assistant configuration
error-log
Manage error log
home-assistant-pp-cli error-log - Get current error log
events
Manage events
home-assistant-pp-cli events fire - Fire an eventhome-assistant-pp-cli events list - List event types
history
Manage history
home-assistant-pp-cli history <timestamp> - Get entity history for a time window
intent
Manage intent
home-assistant-pp-cli intent - Handle an Assist intent
logbook
Manage logbook
home-assistant-pp-cli logbook <timestamp> - Get a logbook time window
services
Manage services
home-assistant-pp-cli services call - Call a Home Assistant servicehome-assistant-pp-cli services list - List service domains and services
states
Manage states
home-assistant-pp-cli states delete - Remove a custom entity statehome-assistant-pp-cli states get - Get an entity statehome-assistant-pp-cli states list - List current entity stateshome-assistant-pp-cli states set - Set a state for a custom entity
template
Manage template
home-assistant-pp-cli template - Render a Home Assistant template
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
home-assistant-pp-cli recall <query> - Look up cached resources for a query before running discoveryhome-assistant-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)home-assistant-pp-cli learnings list - Inspect taught rowshome-assistant-pp-cli learnings forget <query> - Undo a teachhome-assistant-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejecthome-assistant-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countshome-assistant-pp-cli teach-pattern - Install a query/resource template up fronthome-assistant-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set HOME_ASSISTANT_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of home-assistant-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
home-assistant-pp-cli calendars list
# JSON for scripting and agents
home-assistant-pp-cli calendars list --json
# Filter to specific fields
home-assistant-pp-cli calendars list --json --select id,name,status
# Dry run — show the request without sending
home-assistant-pp-cli calendars list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
home-assistant-pp-cli calendars list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Runtime Endpoint
This CLI resolves endpoint placeholders at runtime, so one installed binary can target different tenants or API versions without regeneration.
Endpoint environment variables:
HOME_ASSISTANT_SERVER resolves {server}
Base URL: ``
Health Check
home-assistant-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run home-assistant-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/home-assistant-pp-cli/config.toml; --home, HOME_ASSISTANT_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
HOME_ASSISTANT_SERVER | endpoint | Yes | |
HASS_TOKEN | per_call | No | Set to your API credential. |
HOME_ASSISTANT_BEARER_AUTH | per_call | No | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, home-assistant-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
home-assistant-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $HASS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- 401 Unauthorized — Create a fresh Long-Lived Access Token in the Home Assistant profile and export it as HASS_TOKEN.
- Home Assistant server is unreachable — Set HASS_SERVER to a URL reachable from this machine, including port 8123 when required, then run home-assistant-pp-cli doctor.
- A friendly name matches multiple entities — Re-run with the exact entity_id returned in the ambiguity error; the CLI will not guess.
- A command reports that the installation lacks a capability — Run home-assistant-pp-cli system info --agent and use the reported stock Core, Supervisor, or integration-supported command path.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press