Home Assistant 命令行界面

使用官方 hass-cli 工具控制您的 Home Assistant 智能家居设备——这是一个功能丰富的命令行界面，具备自动补全、事件监控和灵活的输出格式。

为何选择此技能而非homeassistant（基于 curl）？

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

• ✅实体 ID 和服务自动补全（支持 bash/zsh/fish）
• ✅实时事件监控（hass-cli event watch）
• ✅历史查询（hass-cli state history）
• ✅更好的输出格式化（支持表格/YAML/JSON格式，仅需一个标志位）
• ✅交互式探索（更便捷地发现实体与服务）
• ✅完整文档支持包含示例与故障排除指南

选择homeassistant（curl方案）如果您需要：

• ✅ 零依赖（curl + jq 已预装）
• ✅ 轻量快速
• ✅ 更适合脚本与自动化场景
• ✅ 无需Python环境

两种方案都很优秀——本技能专为频繁使用Home Assistant并期望获得更丰富CLI体验的用户设计。

配置指南

使用hass-cli前需先配置认证信息：

1. 在Home Assistant中生成长期访问令牌：

   • 进入您的个人资料页面：https://your-homeassistant:8123/profile
   • 滚动至“长期访问令牌”
   • 创建新令牌

2. 设置环境变量（添加到 shell 配置中以持久保存）：

   export HASS_SERVER=https://homeassistant.local:8123
   export HASS_TOKEN=<your-token>
   

3. 测试连接：

   hass-cli info
   

常用命令

列出实体

# List all entities
hass-cli state list

# Filter by domain
hass-cli state list light
hass-cli state list switch
hass-cli state list sensor

# Get specific entity state
hass-cli state get light.living_room

控制设备

# Turn on/off lights
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

# Set brightness (0-255)
hass-cli service call light.turn_on --arguments entity_id=light.bedroom,brightness=128

# Turn on/off switches
hass-cli service call switch.turn_on --arguments entity_id=switch.fan
hass-cli service call switch.turn_off --arguments entity_id=switch.fan

# Toggle any device
hass-cli service call homeassistant.toggle --arguments entity_id=light.kitchen

列出和调用服务

# List all services
hass-cli service list

# Filter services
hass-cli service list light
hass-cli service list 'home.*toggle'

# Get service details (YAML output)
hass-cli -o yaml service list homeassistant.toggle

处理场景

# List scenes
hass-cli state list scene

# Activate a scene
hass-cli service call scene.turn_on --arguments entity_id=scene.movie_time

监控事件

# Watch all events
hass-cli event watch

# Watch specific event type
hass-cli event watch state_changed
hass-cli event watch automation_triggered

历史记录

# Get state history (last 50 minutes)
hass-cli state history --since 50m light.living_room

# Multiple entities
hass-cli state history --since 1h light.living_room switch.fan

输出格式

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

# Table (default)
hass-cli state list

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

# JSON
hass-cli -o json state list light

# No headers (for scripting)
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以了解常见的自动化模式和用例。