Home Assistant CLI

核心用法

homeassistant-cli 是 Home Assistant 官方维护的 Python 命令行工具，封装了 REST API 的复杂调用，提供交互式探索能力。用户通过 HASS_SERVER 和 HASS_TOKEN 环境变量完成认证后，可执行实体状态查询、服务调用、场景触发、事件监听及历史数据回溯等操作。

核心命令结构遵循 hass-cli <领域> <动作> 模式：

• 状态管理：state list/get 查询实体，service call 执行服务
• 实时监控：event watch 订阅事件流，支持 state_changed 等过滤
• 历史分析：state history --since <时长> 获取时序数据
• 灵活输出：-o yaml/json/table 一键切换格式，兼顾人工阅读与脚本解析

显著优点

1. 官方生态整合：由 Home Assistant 生态系统团队维护，API 兼容性有保障
2. 自动补全：bash/zsh/fish 全支持，大幅降低实体 ID 记忆负担
3. 发现式交互：无需记忆完整实体名，支持通配过滤与交互探索
4. 多格式输出：同一命令适配调试、文档、自动化脚本多种场景
5. 实时监控能力：原生支持事件流订阅，curl 方案难以实现

潜在局限

• Python 依赖：需 Python 3.8+ 及 pip/brew 安装，容器化环境需额外配置
• 初始认证门槛：长有效期令牌生成对新手不够直观
• 性能开销：相比裸 curl，Python 运行时带来约 200-500ms 启动延迟
• 网络耦合：严格依赖 Home Assistant 实例可达性，离线场景完全失效

适合人群

• 日常频繁调试智能家居的开发者/极客用户
• 需要历史数据分析与自动化脚本编写的进阶玩家
• 偏好交互式 CLI 而非纯 HTTP 工具的管理员

常规风险

• 令牌泄露风险：HASS_TOKEN 环境变量可能被进程转储或 shell history 记录，建议配合 export HISTIGNORE 及专用凭证管理工具
• 误操作扩散：服务调用无二次确认，light.turn_off 误触可能影响全屋照明
• 历史查询性能：长时段大范围实体查询可能阻塞 Home Assistant 数据库连接
• TLS 配置：默认建议 HTTPS，自签名证书需额外信任配置

核心用法

homeassistant-cli 是对 Home Assistant 官方 hass-cli 工具的命令行封装，专为需要频繁与智能家居系统交互的用户设计。其核心功能包括：

• 设备控制：通过 hass-cli service call 调用服务，支持灯光、开关、传感器等各类实体的开关、亮度调节、状态切换等操作
• 实体管理：使用 hass-cli state list/get 查询设备状态，支持按域名过滤和精确查找
• 实时监控：hass-cli event watch 可监听 Home Assistant 事件流，便于调试自动化规则
• 历史数据：hass-cli state history 查询设备状态变化历史，支持时间范围定制
• 场景控制：激活预定义场景实现一键式环境切换

配置依赖两个环境变量：HASS_SERVER（服务器地址）和 HASS_TOKEN（长期访问令牌），均通过用户侧配置注入，无硬编码风险。

显著优点

• 交互体验优秀：相比 curl 方案，提供 bash/zsh/fish 自动补全、表格/YAML/JSON 多格式输出，大幅降低记忆成本
• 发现能力强：内置实体和服务发现机制，无需记忆完整 ID 即可探索可用功能
• 官方生态背书：直接封装 Home Assistant 官方 CLI 工具，功能同步更新，社区支持完善
• 零代码执行：Skill 本身为纯 Markdown 文档，无动态代码，仅作命令调用说明
• 安装灵活：支持 pip 和 Homebrew 双渠道安装，覆盖主流开发环境

潜在局限

• 外部依赖必需：需预先安装 hass-cli 工具，对轻量级场景不如 curl 方案便捷
• Python 环境依赖：hass-cli 基于 Python，对纯容器或极简环境不够友好
• 功能边界清晰：作为文档型 Skill，不提供图形界面或自动化编排能力，需用户自行组合命令
• 网络配置敏感：Token 和服务器地址由用户配置，误配置可能导致连接失败或安全隐患

适合人群

• 已部署 Home Assistant 且需要高频交互的智能家居用户
• 偏好命令行工作流、习惯终端操作的开发者和技术爱好者
• 需要编写自动化脚本、批量管理设备的运维人员
• 希望获得比 curl 更友好体验，但不需要图形界面的中级用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| Token 泄露 | 环境变量若写入公共配置文件可能被读取 | 使用 shell 私有配置（如 `.zshrc.local`），避免提交到版本控制 |

| 中间人攻击 | HTTP 明文传输可能被窃听 | 强制 HTTPS 连接，配置 TLS 1.2+ |

| 公网暴露 | 实例暴露于互联网易受扫描攻击 | 建议仅在可信局域网使用，配合 VPN 或反向代理 |

| 权限过大 | 长期 Token 通常具备完整控制权限 | 按需创建最小权限 Token，定期轮换 |

该 Skill 本身无可执行代码，风险主要来源于用户配置和使用习惯，遵循安全最佳实践即可有效管控。