hass-cli v1.0.0 升级踩坑记：4 个 bug 和一个意外发现

为什么写这篇

Home Assistant 有 Web 界面，有 REST API，有 WebSocket——为什么还要折腾命令行？

因为上周家里的 47 个灯突然全显示 unavailable。在 Web 界面逐个检查集成状态花了 20 分钟，而一条命令就能搞定。

hass-cli integration list
# 发现 xiaomi_miot 状态为 not_loaded → 根因找到了

这就是 hass-cli 的价值。v1.0.0 刚发布，带了几个好用的新命令，但也踩了不少坑。这篇记录从升级到实际使用的全过程。

hass-cli 是什么

Home Assistant 的官方命令行工具，PyPI 包名 homeassistant-cli。注意和 Supervisor CLI（Go 写的，命令叫 ha）区分。

三种方式对比：

方式	优点	缺点	适合场景
Web 界面	直观	批量操作慢，调试不便	日常控制
curl	零依赖	需手动构造请求	脚本/快速测试
hass-cli	实体/集成/设备探索，实时事件监控，多输出格式	需安装 pip 包	调试、批量操作、问题排查

安装

我的方式：uv + Python 3.13

uv python install 3.13
uv venv ~/.venvs/hass-cli --python 3.13
uv pip install homeassistant-cli==1.0.0

验证：

~/.venvs/hass-cli/bin/hass-cli --version
# 1.0.0

其他方式

如果你的环境已有 Python 3.13，直接 pip install homeassistant-cli==1.0.0 也行。用 Docker 的话，可以跑一个带 Python 3.13 的容器安装——但我建议装在本地，因为 CLI 需要持久化的 HA token，容器重启会丢。

便捷用法

别每次都敲全路径，加个 alias：

alias ha-cli='~/.venvs/hass-cli/bin/hass-cli --server "http://YOUR_HA_IP:8123" --token "$HASS_TOKEN"'

这样后续所有命令都用 ha-cli 代替 hass-cli --server ... --token ...。

v1.0.0 新增了什么

从 0.9.6 升上来，最实用的三个新命令：

命令	作用	值得升级的理由
`integration list`	查看所有集成的加载状态	一条命令定位设备离线根因
`entity list`	显示实体的平台/区域/设备信息	比 `state list` 多了注册信息
`template`（内联）	支持 stdin Jinja2 模板	不用临时写文件了

integration list 是这次升级的核心价值。以前想知道哪个集成挂了，得去 Web 界面一个个翻。现在：

ha-cli integration list
# name: xiaomi_miot
# state: not_loaded          ← 这就是根因
# ...
# name: sonoff
# state: not_loaded          ← 还有一个

看到 not_loaded，去 Web 界面重启对应集成就行。47 个灯的故障，5 秒定位。

4 个踩坑

坑 1：环境变量不生效

# 你以为这样就行
export HASS_SERVER="http://YOUR_HA_IP:8123"
export HASS_TOKEN="YOUR_TOKEN"
hass-cli state list   # 超时，或者报错

原因不明，可能是 CLI 解析环境变量的某些 edge case。

解法：别依赖环境变量，始终显式传参：

hass-cli --server "http://YOUR_HA_IP:8123" --token "$HASS_TOKEN" state list

或者用 alias 包一层，最省心。

坑 2：raw get URL 拼接 bug

hass-cli raw get "states"          # 报错
hass-cli raw get "/api/states"     # 正常

v1.0.0 在拼接 URL 时，host 和 path 之间少了 /。路径必须带前导 /，写完整 API 路径。这不是什么大问题，但文档没提，踩到了就卡一下。

坑 3：Python 版本不兼容

Python 3.11 → 装的是 v0.9.6（旧版）
Python 3.14 → 装 v1.0.0 后跑不起来，asyncio event loop 报错
Python 3.13 → 刚好

v1.0.0 要求 python_requires >= 3.13，但 3.14 的 asyncio 有兼容问题。用 uv python install 3.13 精确装就行，别赌最新的。

坑 4：info 命令 404

hass-cli info   # 404

新版 HA 弃用了 /api/discovery_info 端点，两版 CLI 都受影响。info 命令等于废了。

替代：用 config release 查版本信息。

命令速查

装好之后，常用命令都在这里：

# 状态查询
ha-cli state list                          # 所有实体
ha-cli state list "switch.*"              # 按前缀过滤
ha-cli state get sensor.xxx               # 单个实体详情
ha-cli --output yaml state get sensor.xxx # YAML 格式

# 结构探索（v1.0.0 新增）
ha-cli entity list                         # 实体注册信息
ha-cli integration list                    # 集成加载状态
ha-cli device list                         # 设备清单
ha-cli area list                           # 区域列表
ha-cli service list                        # 可用服务

# 模板渲染
ha-cli template <<< '{{ states.light | selectattr("state","eq","on") | list | length }}'

# 实时监控
ha-cli event watch                         # 实时事件流

# 原始 API
ha-cli --output json raw get "/api/states"

实战：5 秒定位设备离线

回到开头的场景——47 个灯全部 unavailable。

# 第一步：查集成状态
ha-cli integration list | grep -A2 "xiaomi_miot"
# name: xiaomi_miot
# state: not_loaded    ← 找到了

# 第二步：去 Web 界面重启 xiaomi_miot 集成

# 第三步：验证
ha-cli integration list | grep -A2 "xiaomi_miot"
# name: xiaomi_miot
# state: loaded        ← 恢复了

# 灯回来了（36/44 = 82%，其余是其他问题）

没有 integration list，这个排查过程至少要 15-20 分钟。有了它，从发现问题到定位根因不到 1 分钟。

总结

hass-cli v1.0.0 值得升级，但别指望开箱即用。记住三件事：

用 Python 3.13，别赌 3.14
别信环境变量，显式传 --server 和 --token
raw get 路径带前导 /

integration list 是这次升级最大的收获，尤其是排查设备离线问题——一条命令顶 20 分钟的 Web 界面翻找。