Problem statement
Home Assistant has no official CLI. There is a community-maintained hass-cli project, but it covers only a subset of the HA API, and is not designed with AI agent use in mind.
This matters because AI coding agents increasingly operate natively in the terminal. When these agents need to interact with external services, they reach for CLIs first: the token cost is a fraction of MCP, reliability is higher, and frontier models have deep training on shell patterns. Without an official HA CLI, AI agents cannot efficiently control a home, author automations, manage dashboards, or manipulate scripts and scenes from the terminal.
Community signals
TODO: extend
hass-cli exists as evidence of demand.- The broader developer tooling ecosystem is converging on CLIs as the preferred AI agent interface in 2026; HA risks falling behind tools that offer both MCP and CLI access.
- AI assistant users building home automations today must work around the absence of a CLI by copy-pasting YAML or navigating the UI manually, even when operating from a terminal-native workflow.
Scope & Boundaries
In scope
- Home control — controlling devices and querying state (on/off, brightness, cover position, etc.), equivalent to what the MCP server's assist pipeline exposes today.
Automation authoring — listing, creating, updating, enabling/disabling, and deleting automations.
- Script & scene management — listing, creating, updating, and deleting scripts and scenes.
- Dashboard management — creating and modifying Lovelace dashboards and cards.
- Authentication — token-based auth with support for long-lived access tokens; no dependency on UI login.
- Output formats — structured output (JSON) alongside human-readable defaults, so AI agents and scripts can parse results reliably.
Not in scope
- Entity and device registry management
- Integration setup and configuration
- Add-on and supervisor management
- A REPL or interactive shell mode
- Replacing or wrapping
hass-cli (this would be a new, official tool)
Foreseen solution
An official ha CLI distributed as a standalone binary (and ideally via common package managers: Homebrew, apt, winget). The CLI wraps the existing HA REST API and WebSocket interface, with subcommands organised around capability areas:
ha state get <entity_id>
ha state set <entity_id> --state on
ha automation list
ha automation create --file automation.yaml
ha script run <script_id>
ha dashboard create --file dashboard.yaml
Output defaults to human-readable tables; --output json enables machine-parseable output for scripting and agent use. Authentication is configured once via ha auth login storing a long-lived token.
The tool should be thin. A well-designed CLI wrapper over existing APIs, not a new backend. Parity with the expanded MCP server scope (from the companion roadmap opportunity) should be a design constraint from day one, so both surfaces expose the same capabilities.
Risks & open questions
- Relationship to
hass-cli: Should this supersede it, absorb it, or coexist? Fragmenting the ecosystem further is a risk; ignoring prior community work is a missed opportunity.
- Distribution and versioning: The CLI must stay in sync with the HA API. How is versioning handled when HA evolves faster than a standalone binary release cycle?
- Authentication UX: Long-lived access tokens are powerful. How does the CLI handle token storage securely across platforms? Does it support instance switching (e.g., local vs. remote)?
- Windows support: Many HA users manage their setup from Windows machines. The CLI needs to be genuinely cross-platform, not just technically portable.
- Scope creep risk: A CLI is an attractive surface. Keeping it focused and not letting it become a full HA admin tool will require active curation.
Appetite
Medium. The underlying APIs are mature. The investment is in CLI design, cross-platform distribution, and ongoing maintenance as an official OHF-supported tool, the latter being the real long-term commitment.
Execution issues
No response
Decision log
Problem statement
Home Assistant has no official CLI. There is a community-maintained
hass-cliproject, but it covers only a subset of the HA API, and is not designed with AI agent use in mind.This matters because AI coding agents increasingly operate natively in the terminal. When these agents need to interact with external services, they reach for CLIs first: the token cost is a fraction of MCP, reliability is higher, and frontier models have deep training on shell patterns. Without an official HA CLI, AI agents cannot efficiently control a home, author automations, manage dashboards, or manipulate scripts and scenes from the terminal.
Community signals
TODO: extend
hass-cliexists as evidence of demand.Scope & Boundaries
In scope
Automation authoring — listing, creating, updating, enabling/disabling, and deleting automations.
Not in scope
hass-cli(this would be a new, official tool)Foreseen solution
An official ha CLI distributed as a standalone binary (and ideally via common package managers: Homebrew, apt, winget). The CLI wraps the existing HA REST API and WebSocket interface, with subcommands organised around capability areas:
Output defaults to human-readable tables;
--output jsonenables machine-parseable output for scripting and agent use. Authentication is configured once viaha auth loginstoring a long-lived token.The tool should be thin. A well-designed CLI wrapper over existing APIs, not a new backend. Parity with the expanded MCP server scope (from the companion roadmap opportunity) should be a design constraint from day one, so both surfaces expose the same capabilities.
Risks & open questions
hass-cli: Should this supersede it, absorb it, or coexist? Fragmenting the ecosystem further is a risk; ignoring prior community work is a missed opportunity.Appetite
Medium. The underlying APIs are mature. The investment is in CLI design, cross-platform distribution, and ongoing maintenance as an official OHF-supported tool, the latter being the real long-term commitment.
Execution issues
No response
Decision log