核心用法
homeassistant-cli 是 Home Assistant 官方维护的 Python 命令行工具，封装了 REST API 的复杂调用，提供交互式探索能力。用户通过 HASS_SERVER 和 HASS_TOKEN 环境变量完成认证后，可执行实体状态查询、服务调用、场景触发、事件监听及历史数据回溯等操作。
核心命令结构遵循 hass-cli <领域> <动作> 模式：
- 状态管理：
state list/get查询实体，service call执行服务 - 实时监控：
event watch订阅事件流，支持state_changed等过滤 - 历史分析：
state history --since <时长>获取时序数据 - 灵活输出：
-o yaml/json/table一键切换格式，兼顾人工阅读与脚本解析
显著优点
1. 官方生态整合：由 Home Assistant 生态系统团队维护，API 兼容性有保障
2. 自动补全：bash/zsh/fish 全支持，大幅降低实体 ID 记忆负担
3. 发现式交互：无需记忆完整实体名，支持通配过滤与交互探索
4. 多格式输出：同一命令适配调试、文档、自动化脚本多种场景
5. 实时监控能力：原生支持事件流订阅，curl 方案难以实现
潜在局限
- Python 依赖：需 Python 3.8+ 及 pip/brew 安装，容器化环境需额外配置
- 初始认证门槛：长有效期令牌生成对新手不够直观
- 性能开销：相比裸 curl，Python 运行时带来约 200-500ms 启动延迟
- 网络耦合：严格依赖 Home Assistant 实例可达性，离线场景完全失效
适合人群
- 日常频繁调试智能家居的开发者/极客用户
- 需要历史数据分析与自动化脚本编写的进阶玩家
- 偏好交互式 CLI 而非纯 HTTP 工具的管理员
常规风险
- 令牌泄露风险：
HASS_TOKEN环境变量可能被进程转储或 shell history 记录，建议配合export HISTIGNORE及专用凭证管理工具 - 误操作扩散：服务调用无二次确认，
light.turn_off误触可能影响全屋照明 - 历史查询性能：长时段大范围实体查询可能阻塞 Home Assistant 数据库连接
- TLS 配置：默认建议 HTTPS，自签名证书需额外信任配置