hass-cli v1.0.0 安装与已知 Bug 排查

装了个 CLI，比装 HA 本身还折腾

Home Assistant 官方提供了一个命令行工具 hass-cli（PyPI 包名 homeassistant-cli），让你不用开浏览器、直接在终端里查状态、调服务、看实时事件。

听起来很好用。但装完 v1.0.0 发现——嗯？跟 v0.9.6 的命令不一样？环境变量设了没反应？info 直接 404？

安装：Python 版本是第一个坑

homeassistant-cli v1.0.0 要求 Python ≥ 3.13。如果你用系统默认的 Python 3.11，pip install 拉下来的是 v0.9.6（旧版），不是新版。如果你用 Python 3.14，安装 v1.0.0 倒是可以，但运行时可能出现 asyncio event loop 错误。

最佳方案是用 Python 3.13，配合 uv 管理：

# 1. 安装 Python 3.13
uv python install 3.13

# 2. 创建独立 venv
uv venv ~/.venvs/hass-cli --python 3.13

# 3. 安装 hass-cli
uv pip install homeassistant-cli==1.0.0

# 4. 验证
~/.venvs/hass-cli/bin/hass-cli --version
# 输出：1.0.0

注意：homeassistant-cli 跟 Supervisor 的 ha CLI 是两回事，前者是 Python CLI，后者是 Go 写的 Docker 管理工具。

v1.0.0 新增了什么

跟 v0.9.6 对比，v1.0.0 有几个重要变化：

命令	v0.9.6	v1.0.0	说明
`entity list`	无	✅ 新增	显示实体注册信息（平台/区域/设备）
`integration list`	无	✅ 新增	看集成加载状态
`template`	需文件	✅ 支持内联	stdin 直接传模板
`info`	❌ 404	❌ 404	两版都坏，HA 弃用了端点
`raw get`	✅	⚠️ URL 拼接 bug	路径前需加 `/`

最有价值的新增命令是 integration list——后文会讲一个用它救急的实战案例。

4 个踩坑

踩坑 1：环境变量设了没反应

设置了 HASS_SERVER 和 HASS_TOKEN 后，hass-cli state list 可能超时或报错。原因不明确，可能是 CLI 解析环境变量时的 edge case。

解决方案：始终显式传参，别依赖环境变量。

# ✅ 可靠
hass-cli --server "http://192.168.31.229:8123" --token "$HASS_TOKEN" state list

# ❌ 可能超时
export HASS_SERVER="http://192.168.31.229:8123"
hass-cli state list

踩坑 2：raw get URL 拼接缺 `/`

hass-cli raw get "states" 返回错误。检查发现 v1.0.0 拼接 URL 时，host 和 path 之间少了一个 /。

# ✅ 正确
hass-cli raw get "/api/states"

# ❌ 错误
hass-cli raw get "states"

路径前加 / 即可。这个 bug 是显性的，用一次就发现，绕过也很简单。

踩坑 3：Python 版本要精确到 3.13

v1.0.0 要求 Python ≥ 3.13，但在 Python 3.14 上运行会报 asyncio event loop 错误。必须精确到 3.13：

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

踩坑 4：info 命令永远 404

hass-cli info 在 v0.9.6 和 v1.0.0 上都返回 404。原因是新版 HA 已弃用 /api/discovery_info 端点。

# ❌ 永远 404
hass-cli info

# ✅ 替代方案
hass-cli config release

用 config release 获取 HA 版本信息即可。

实战：integration list 救了我一次

家里 47 个灯突然全部显示 unavailable。从 HA Web 界面看，每个灯都点进去看？不现实。

hass-cli integration list 一行命令就锁定了根因：

ha-cli integration list
# 输出显示 xiaomi_miot 状态为 not_loaded
# sonoff 集成也是 not_loaded

xiaomi_miot 未加载 = 所有小米设备 unavailable。原因可能是 HA 重启后集成加载超时。

在 HA Web 界面重新加载 xiaomi_miot 集成后，36/44 个灯恢复可用（余下 8 个是蓝牙 mesh 灯，本身不稳定）。

integration list 是 v1.0.0 最有价值的命令。之前要排查这类问题，得在 HA 设置→集成页面逐个点开看加载状态，没法批量。现在一行命令就出全貌。

命令速查

# 设置便捷变量
HASS_SERVER="http://YOUR_HA_IP:8123"
HASS_TOKEN="YOUR_TOKEN"
HC="~/.venvs/hass-cli/bin/hass-cli --server $HASS_SERVER --token $HASS_TOKEN"

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

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

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

# 实时监控
$HC event watch                        # 实时事件流

# 原始 API
$HC --output json raw get "/api/states" # 原始 API 调用

总结

hass-cli v1.0.0 是个实用的 CLI 工具，但升级路上要跨 4 个坑：

Python 版本 → 必须 3.13，别的版本踩坑
环境变量 → 不要信环境变量，显式传 --server --token
raw get URL → 路径前加 /
info 404 → 用 config release 替代

跨过去之后，integration list 和 entity list 这两个新增命令让 HA 运维效率提升不少——尤其是一行命令查出所有集成加载状态的能力。