Home Assistant CLI

# Home Assistant CLI

使用 **官方 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` - 滚动到“Long-Lived Access Tokens”（长期访问令牌） - 创建一个新令牌

2. 设置环境变量（添加到 shell 配置中以持久化）： ```bash export HASS_SERVER=https://homeassistant.local:8123 export HASS_TOKEN=<your-token> ```

3. 测试连接： ```bash hass-cli info ```

## 常用命令

### 列出实体

```bash # 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 ```

### 控制设备

```bash # 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 ```

### 列出和调用服务

```bash # 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 ```

### 使用场景

```bash # List scenes hass-cli state list scene

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

### 监控事件

```bash # Watch all events hass-cli event watch

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

### 历史记录

```bash # 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` 控制输出：

```bash # 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](references/autocomplete.md) 了解 shell 设置 - **故障排除**：查看 [references/troubleshooting.md](references/troubleshooting.md)

## 示例

查看 [references/examples.md](references/examples.md) 了解常见的自动化模式和用例。