homeassistant-cli 0.9.6

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

Home Assistant命令行界面（hass-cli）允许您直接从命令行与本地或远程的Home Assistant Core或Home Assistant（前身为Hass.io）实例交互。

安装

使用最新发布版

$ pip install homeassistant-cli

使用来自dev分支的最新预发布版

$ pip install git+https://github.com/home-assistant-ecosystem/home-assistant-cli@dev

hass-cli的开发者通常为最近的Fedora和EPEL发布版提供最新的软件包。使用dnf进行安装

$ sudo  dnf -y install home-assistant-cli

社区通过homebew为macOS提供支持。

$ brew install homeassistant-cli

请注意，发行版中可用的版本可能已过时。

home-assistant-cli也适用于NixOS。

要在NixOS上使用此工具，请注意最新版本可能仅在unstable通道中可用。

$ nix-env -iA nixos.home-assistant-cli

$ docker run homeassistant/home-assistant-cli

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

设置

要开始，您需要在您的Home Assistant配置文件页上拥有或生成一个长期有效的令牌格式（例如，在https://localhost:8123/profile中向下滚动到“长期访问令牌”）。

然后您可以在每次调用时使用--server和--token参数，或者建议设置HASS_SERVER和HASS_TOKEN环境变量。

$ export HASS_SERVER=https://homeassistant.local:8123
$ export HASS_TOKEN=<secret>

一旦启用，运行以下命令之一以启用hass-cli命令的自动补全。

$ source <(_HASS_CLI_COMPLETE=bash_source hass-cli) # for bash
$ source <(_HASS_CLI_COMPLETE=zsh_source hass-cli)  # for zsh
$ eval (_HASS_CLI_COMPLETE=fish_source hass-cli)    # for fish

用法

注意：以下列出了一些功能，请确保使用--help和自动补全来了解更多的功能，因为这些功能成为可用。

大多数命令返回Home Assistant API返回的表格版本。例如，要获取有关您的Home Assistant服务器的基本信息，请使用info。

$ hass-cli info
  BASE_URL                           LOCATION         REQUIRES_API_PASWORD  VERSION
  https://home-assistant.local:8123  Fort of Solitude False                 0.86.2

如果您更喜欢yaml，可以使用--output=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

要获取状态列表，请使用state list。

$ hass-cli state list
ENTITY                                                     DESCRIPTION                                     STATE
zone.school                                                School                                          zoning
zone.home                                                  Andersens                                       zoning
sun.sun                                                    Sun                                             below_horizon
camera.babymonitor                                         babymonitor                                     idle
timer.timer_office_lights                                                                                  idle
timer.timer_small_bathroom                                                                                 idle
[...]

您可以使用--no-headers来抑制标题。

--table-format让您选择您想要的表格格式。默认为simple，但您可以使用https://pypi.ac.cn/project/tabulate/支持的所有格式：plain、simple、github、grid、fancy_grid、pipe、orgtbl、rst、mediawiki、html、latex、latex_raw、latex_booktabs或tsv。

最后，您还可以通过--columns显式控制要显示哪些数据。每个列都有一个名称和jsonpath。实体的默认设置是

--columns=ENTITY=entity_id,DESCRIPTION=attributes.friendly_name,STATE=state,CHANGED=last_changed

例如，如果您只想获取名称和所有属性，可以这样做

$ hass-cli --columns=ENTITY="entity_id,ATTRIBUTES=attributes[*]" state list zone
ENTITY             ATTRIBUTES
zone.school        {'friendly_name': 'School', 'hidden': True, 'icon': 'mdi:school', 'latitude': 7.011023, 'longitude': 16.858151, 'radius': 50.0}
zone.unnamed_zone  {'friendly_name': 'Unnamed zone', 'hidden': True, 'icon': 'mdi:home', 'latitude': 37.006476, 'longitude': 2.861699, 'radius': 50.0}
zone.home          {'friendly_name': 'Andersens', 'hidden': True, 'icon': 'mdi:home', 'latitude': 27.006476, 'longitude': 7.861699, 'radius': 100}

您可以使用yaml或json输出格式获取状态的更多详细信息。在这个例子中，我们使用了输出缩写：-o

$ 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"}'

列出带或不带正则表达式过滤器的可能服务

$ hass-cli service list 'home.*toggle'
  DOMAIN         SERVICE    DESCRIPTION
  homeassistant  toggle     Generic service to toggle devices on/off...

更多详细信息，YAML格式非常有用

$ hass-cli -o yaml service list homeassistant.toggle
homeassistant:
  services:
    toggle:
      description: Generic service to toggle devices on/off under any domain. Same
        usage as the light.turn_on, switch.turn_on, etc. services.
      fields:
        entity_id:
          description: The entity_id of the device to toggle on/off.
          example: light.living_room

您可以获得关于一个或多个实体的历史记录，这里获取过去50分钟的状态变化

$ hass-cli state history --since 50m light.kitchen_light_1 binary_sensor.presence_kitchen
  ENTITY                          DESCRIPTION      STATE    CHANGED
  binary_sensor.presence_kitchen  Kitchen Motion   off      2019-01-27T23:19:55.322474+00:00
  binary_sensor.presence_kitchen  Kitchen Motion   on       2019-01-27T23:21:44.015071+00:00
  binary_sensor.presence_kitchen  Kitchen Motion   off      2019-01-27T23:22:02.330566+00:00
  light.kitchen_light_1           Kitchen Light 1  on       2019-01-27T23:19:55.322474+00:00
  light.kitchen_light_1           Kitchen Light 1  off      2019-01-27T23:36:45.254266+00:00

默认情况下，数据按Home Assistant返回的顺序排序，因此对于历史记录，按属性排序很有用

$ hass-cli --sort-by last_changed state history --since 50m  light.kitchen_light_1 binary_sensor.presence_kitchen
ENTITY                          DESCRIPTION      STATE    CHANGED
binary_sensor.presence_kitchen  Kitchen Motion   off      2019-01-27T23:18:00.717611+00:00
light.kitchen_light_1           Kitchen Light 1  on       2019-01-27T23:18:00.717611+00:00
binary_sensor.presence_kitchen  Kitchen Motion   on       2019-01-27T23:18:12.135015+00:00
binary_sensor.presence_kitchen  Kitchen Motion   off      2019-01-27T23:18:30.417064+00:00
light.kitchen_light_1           Kitchen Light 1  off      2019-01-27T23:36:45.254266+00:00

注意：–sort-by参数是指底层json/yaml中的属性，而不是列名。这样做的好处是，即使没有包含在默认输出中，也可以用于对任何属性进行排序。

$ hass-cli device list
ID                                NAME                           MODEL                            MANUFACTURER        AREA
a3852c3c3ebd47d3acac195478ca6f8b  Basement stairs motion         SML001                           Philips             c6c962b892064a218e968fcaee7950c8
880a944e74db4bb48ea3db6dd24af357  Basement Light 2               TRADFRI bulb GU10 WS 400lm       IKEA of Sweden      c6c962b892064a218e968fcaee7950c8
657c3cc908594479aab819ff80d0c710  Office                         Hue white lamp                   Philips             None
[...]

$ hass-cli area list
ID                                NAME
295afc88012341ecb897cd12d3fbc6b4  Bathroom
9e08d89203804d5db995c3d0d5dbd91b  Winter Garden
8816ee92b7b84f54bbb30a68b877e739  Office
[...]

$ hass-cli area delete "Old Shed"
-  id: 1
   type: result
   success: true
   result: success

$ hass-cli area create "New Shed"
-  id: 1
   type: result
   success: true
   result:
       area_id: cdd09a80f03a4cc59d2943053c0414c0
       name: New Shed

$ hass-cli device assign Kitchen "Cupboard Light"

$ hass-cli device assign Kitchen --match "Kitchen Light"

$ hass-cli device assign Kitchen --match "Kitchen Light" eab9930f8652408882cc8cb604651c60 Cupboard

$ hass-cli event watch

$ hass-cli event watch deconz_event

$ hass-cli ha supervisor info
result: ok
data:
 version: '217'
 version_latest: '217'
 channel: stable
 [...]

$ hass-cli ha core info
result: ok
data:
    version: 0.108.2
    version_latest: 0.108.3
    [...]

$ hass-cli ha core update

$ hass-cli service call deconz.device_refresh

$ hass-cli service call homeassistant.toggle --arguments entity_id=light.office_light

$ hass-cli map

$ hass-cli template motionlight.yaml.j2 motiondata.yaml

$ hass-cli template --local lovelace-template.yaml

eval "$(_HASS_CLI_COMPLETE=source_zsh hass-cli)"

eval "$(_HASS_CLI_COMPLETE=source hass-cli)"

$ hass-cli state get light.<TAB>                                                                                                                                                                    ⏎ ✱ ◼
light.kitchen_light_5          light.office_light             light.basement_light_4         light.basement_light_9         light.dinner_table_light_4     light.winter_garden_light_2    light.kitchen_light_2
light.kitchen_table_light_1    light.hallroom_light_2         light.basement_light_5         light.basement_light_10        light.dinner_table_wall_light  light.winter_garden_light_4    light.kitchen_table_light_2
light.kitchen_light_1          light.hallroom_light_1         light.basement_light_6         light.small_bathroom_light     light.dinner_table_light_5     light.winter_garden_light_3    light.kitchen_light_4
[...]

export HASS_SERVER=http://homeassistant.local:8123
export HASS_TOKEN=eyJ0eXAiO-----------------------ed8mj0NP8

$ hass-cli
Usage: hass-cli [OPTIONS] COMMAND [ARGS]...

  Command line interface for Home Assistant.

Options:
  -l, --loglevel LVL              Either CRITICAL, ERROR, WARNING, INFO or
                                  DEBUG
  --version                       Show the version and exit.
  -s, --server TEXT               The server URL or `auto` for automatic
                                  detection. Can also be set with the
                                  environment variable HASS_SERVER.  [default:
                                  auto]
  --token TEXT                    The Bearer token for Home Assistant
                                  instance. Can also be set with the
                                  environment variable HASS_TOKEN.
  --password TEXT                 The API password for Home Assistant
                                  instance. Can also be set with the
                                  environment variable HASS_PASSWORD.
  --timeout INTEGER               Timeout for network operations.  [default:
                                  5]
  -o, --output [json|yaml|table|ndjson|auto]
                                  Output format.  [default: auto]
  -v, --verbose                   Enables verbose mode.
  -x                              Print backtraces when exception occurs.
  --cert TEXT                     Path to client certificate file (.pem) to
                                  use when connecting.
  --insecure                      Ignore SSL Certificates. Allow to connect to
                                  servers with self-signed certificates. Be
                                  careful!
  --debug                         Enables debug mode.
  --columns TEXT                  Custom columns key=value list. Example:
                                  ENTITY=entity_id,
                                  NAME=attributes.friendly_name
  --no-headers                    When printing tables don't use headers
                                  (default: print headers)
  --table-format TEXT             Which table format to use.
  --sort-by TEXT                  Sort table by the jsonpath expression.
                                  Example: last_changed
  --help                          Show this message and exit.

Commands:
  area        Get info and operate on areas from Home Assistant...
  completion  Output shell completion code for the specified shell (bash or...
  config      Get configuration from a Home Assistant instance.
  device      Get info and operate on devices from Home Assistant...
  discover    Discovery for the local network.
  entity      Get info on entities from Home Assistant.
  event       Interact with events.
  ha          Home Assistant (former Hass.io) commands.
  info        Get basic info from Home Assistant.
  map         Show the location of the config or an entity on a map.
  raw         Call the raw API (advanced).
  service     Call and work with services.
  state       Get info on entity state from Home Assistant.
  system      System details and operations for Home Assistant.
  template    Render templates on server or locally.

$ pip3 install --editable .

$ python3 -m venv .
$ source bin/activate
$ script/setup

$ hass-cli