homeassistant/home-assistant-cli

Home Assistant命令行界面（hass-cli）

镜像概述和主要用途

Home Assistant命令行界面（hass-cli）是一个允许直接从命令行与本地或远程https://home-assistant.io Core或Home Assistant（原Hass.io）实例交互的工具。通过该工具，用户可以便捷地管理Home Assistant实体状态、调用服务、操作设备和区域、监听事件等。

核心功能和特性

• 多实例支持：可连接本地或远程Home Assistant实例
• 状态管理：查看、编辑实体状态，支持多种输出格式（表格、JSON、YAML）
• 服务交互：列出服务、调用服务并传递参数
• 设备与区域管理：列出、创建、删除区域，分配设备到区域
• 事件监听：订阅并监控所有或特定类型的事件
• Home Assistant系统管理：与Supervisor交互，检查和更新Core版本
• 模板渲染：支持服务器端和客户端模板渲染
• 自动补全：支持bash和zsh的命令自动补全

使用场景和适用范围

• 系统管理员通过命令行快速管理Home Assistant实例
• 自动化脚本中集成Home Assistant操作
• 开发人员调试Home Assistant实体和服务
• 需要远程管理Home Assistant实例的场景

详细使用方法和配置说明

安装（Docker方式）

若没有Python环境，可通过Docker容器使用hass-cli：

bash
$ docker run homeassistant/home-assistant-cli

为实现自动补全和环境变量访问，需创建执行脚本：

bash
$ curl https://raw.githubusercontent.com/home-assistant/home-assistant-cli/master/docker-hass-cli > hass-cli
$ chmod +x hass-cli

将脚本放入系统路径后，即可像本地安装一样使用（除需要文件系统访问的命令如hass-cli template）。

环境配置

1. 获取访问令牌：在Home Assistant个人资料页面（如https://localhost:8123/profile）生成长期访问令牌

2. 设置环境变量（推荐）：

   bash
   $ export HASS_SERVER=https://homeassistant.local:8123
   $ export HASS_TOKEN=<你的令牌>
   

   也可在每次命令中使用--server和--token参数指定

3. 启用自动补全：

   • zsh：

     bash
     $ source <(hass-cli completion zsh)
     # 永久启用（推荐）
     $ echo 'eval "$(_HASS_CLI_COMPLETE=source_zsh hass-cli)"' >> ~/.zshrc
     

   • bash：

     bash
     $ source <(hass-cli completion bash)
     # 永久启用（推荐）
     $ echo 'eval "$(_HASS_CLI_COMPLETE=source hass-cli)"' >> ~/.bashrc
     

基本使用示例

获取Home Assistant服务器信息

bash
# 表格格式（默认）
$ hass-cli info
  BASE_URL                           LOCATION         REQUIRES_API_PASWORD  VERSION
  https://home-assistant.local:8123  Fort of Solitude False                 0.86.2

# YAML格式
$ hass-cli --output yaml info
base_url: https://home-assistant.local:8123
location_name: Wayne Manor
requires_api_password: false
version: 0.86.2

管理实体状态

bash
# 列出所有实体状态
$ hass-cli state list

# 查看特定实体详情（YAML格式）
$ hass-cli -o yaml state get light.guestroom_light
attributes:
  friendly_name: Guestroom Light
  supported_features: 61
context:
  id: 84d52fe306ec4895948b546b492702a4
  user_id: null
entity_id: light.guestroom_light
last_changed: '2018-12-10T18:33:51.883238+00:00'
last_updated: '2018-12-10T18:33:51.883238+00:00'
state: 'off'

# 编辑实体状态（通过编辑器）
$ hass-cli state edit light.guestroom_light

# 直接设置实体状态（JSON方式）
$ hass-cli state edit sensor.test --json='{ "state":"off"}'

服务操作

bash
# 列出匹配正则表达式的服务
$ hass-cli service list 'home.*toggle'
  DOMAIN         SERVICE    DESCRIPTION
  homeassistant  toggle     Generic service to toggle devices on/off...

# 调用服务
$ hass-cli service call homeassistant.toggle --arguments entity_id=light.office_light

设备与区域管理

bash
# 列出设备
$ hass-cli device list
ID                                NAME                           MODEL                            MANUFACTURER        AREA
a3852c3c3ebd47d3acac195478ca6f8b  Basement stairs motion         SML001                           Philips             c6c962b892064a218e968fcaee7950c8

# 列出区域
$ hass-cli area list
ID                                NAME
295afc88012341ecb897cd12d3fbc6b4  Bathroom

# 创建区域
$ hass-cli area create "New Shed"

# 分配设备到区域
$ hass-cli device assign Kitchen "Cupboard Light"
# 批量分配设备到区域
$ hass-cli device assign Kitchen --match "Kitchen Light"

事件监听

bash
# 监听所有事件
$ hass-cli event watch

# 监听特定事件
$ hass-cli event watch deconz_event

Home Assistant系统管理

bash
# 查看Supervisor信息
$ hass-cli ha supervisor info

# 查看Core版本信息
$ hass-cli ha core info

# 更新Core到最新版本
$ hass-cli ha core update

命令选项说明

通过hass-cli --help查看所有选项，主要包括：

• -s, --server：Home Assistant服务器URL（环境变量HASS_SERVER）
• --token：访问令牌（环境变量HASS_TOKEN）
• -o, --output：输出格式（json/yaml/table/auto，默认auto）
• --columns：自定义表格列（如ENTITY=entity_id,NAME=attributes.friendly_name）
• --sort-by：按指定属性排序（使用JSONPath表达式）
• --insecure：忽略SSL证书验证（适用于自签名证书）

高级功能

• 历史记录查询：查看实体状态历史

  bash
  $ hass-cli state history --since 50m light.kitchen_light_1
  

• 模板渲染：

  bash
  # 服务器端渲染
  $ hass-cli template motionlight.yaml.j2 motiondata.yaml
  # 客户端渲染
  $ hass-cli template --local lovelace-template.yaml
  

• 地图查看：打开Home Assistant位置地图

  bash
  $ hass-cli map