Home Assistant CLI

使用官方 hass-cli 工具控制您的 Home Assistant 智能家居设备——这是一款功能丰富的命令行接口，支持自动补全、事件监控以及灵活的输出格式化。

为何选择本技能，而非基于 curl 的 homeassistant？

若您需要以下功能，请选择 homeassistant-cli：

• ✅ 支持实体 ID 与服务名称的自动补全（bash/zsh/fish）
• ✅ 支持实时事件监控（hass-cli event watch）
• ✅ 支持历史状态查询（hass-cli state history）
• ✅ 提供更优的输出格式化能力（仅需一个标志即可切换为表格/YAML/JSON 格式）
• ✅ 支持交互式探索（更便于发现实体与服务）
• ✅ 提供全面的文档支持，含示例与故障排查指南

若您需要以下特性，请选择基于 curl 的 homeassistant：

• ✅ 零依赖（curl + jq 通常已预装）
• ✅ 轻量且快速
• ✅ 更适合脚本编写与自动化任务
• ✅ 无需 Python 运行环境

两者均表现优异——本技能面向频繁操作 Home Assistant 的用户，旨在提供更丰富的 CLI 使用体验。

配置

使用 hass-cli 前，请先完成身份验证配置：

1. 在 Home Assistant 中生成长期访问令牌（Long-Lived Access Token）：

   • 进入个人资料页面：https://your-homeassistant:8123/profile
   • 滚动至“长期访问令牌（Long-Lived Access Tokens）”区域
   • 创建新令牌

2. 设置环境变量（建议添加至 Shell 配置文件以实现持久化）：

   export HASS_SERVER=https://homeassistant.local:8123
   export HASS_TOKEN=
   

3. 测试连接：

   hass-cli info
   

常用命令

列出实体

# 列出所有实体
hass-cli state list

# 按领域（domain）筛选
hass-cli state list light
hass-cli state list switch
hass-cli state list sensor

# 获取指定实体的状态
hass-cli state get light.living_room

控制设备

# 开启/关闭灯光
hass-cli service call light.turn_on --arguments entity_id=light.living_room
hass-cli service call light.turn_off --arguments entity_id=light.living_room

# 设置亮度（0–255）
hass-cli service call light.turn_on --arguments entity_id=light.bedroom,brightness=128

# 开启/关闭开关
hass-cli service call switch.turn_on --arguments entity_id=switch.fan
hass-cli service call switch.turn_off --arguments entity_id=switch.fan

# 切换任意设备状态
hass-cli service call homeassistant.toggle --arguments entity_id=light.kitchen

列出并调用服务

# 列出所有服务
hass-cli service list

# 按名称筛选服务
hass-cli service list light
hass-cli service list 'home.*toggle'

# 获取服务详情（YAML 格式输出）
hass-cli -o yaml service list homeassistant.toggle

场景（Scene）操作

# 列出所有场景
hass-cli state list scene

# 激活指定场景
hass-cli service call scene.turn_on --arguments entity_id=scene.movie_time

事件监控

# 监控所有事件
hass-cli event watch

# 监控特定类型事件
hass-cli event watch state_changed
hass-cli event watch automation_triggered

历史状态

# 获取状态历史（最近 50 分钟）
hass-cli state history --since 50m light.living_room

# 查询多个实体的历史状态
hass-cli state history --since 1h light.living_room switch.fan

输出格式

使用 -o 或 --output 控制输出格式：

# 表格格式（默认）
hass-cli state list

# YAML 格式
hass-cli -o yaml state get light.living_room

# JSON 格式
hass-cli -o json state list light

# 不显示表头（适用于脚本处理）
hass-cli --no-headers state list

使用提示

• 实体发现：使用 hass-cli state list 查找实体 ID
• 服务发现：使用 hass-cli service list 查找可用服务
• 自动补全：详见参考文档 references/autocomplete.md 中的 Shell 配置说明
• 故障排查：详见参考文档 references/troubleshooting.md

示例

常见自动化模式与使用场景请参阅 references/examples.md。