Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

💻 Command-line tool for Home Assistant

License

NotificationsYou must be signed in to change notification settings

home-assistant-ecosystem/home-assistant-cli

Repository files navigation

Home Assistant Command-line Interface (hass-cli)

CoverallsLicensePyPI release

The Home Assistant Command-line interface (hass-cli) allows one towork with a local or a remoteHome AssistantCore or Home Assistant (former Hass.io) instance directly from the command-line.

hass-cli screencast

Installation

To use latest release:

$ pip install homeassistant-cli

To use latest pre-release fromdev branch:

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

The developers of hass-cli usually provide up-to-datepackages for recent Fedora and EPEL releases. Usednf for the installation:

$ sudo  dnf -y install home-assistant-cli

The community is providing support for macOS throughhomebew.

$ brew install homeassistant-cli

Keep in mind that the available releases in the distribution could be out-dated.

home-assistant-cli is also available for NixOS.

To use the tool on NixOS. Keep in mind that the latest release could onlybe available in theunstable channel.

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

Docker

If you do not have a Python setup you can try usehass-cli via a containerusing Docker.

$ docker run homeassistant/home-assistant-cli

To make auto-completion and access environment work like other scripts you'llneed to create a script file to execute.

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

Now put thehass-cli script into your path and you can use it like if youhad installed it via command line as long as you don't need file system access(like forhass-cli template).

Setup

To get started you'll need to have or generate a long lasting token formaton your Home Assistant profile page (i.e.https://localhost:8123/profilethen scroll down to "Long-Lived Access Tokens").

Then you can use--server and--token parameter on each call or as isrecommended setupHASS_SERVER andHASS_TOKEN environment variables.

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

Once that is enabled, run one of the following commands to enableautocompletion forhass-cli commands.

$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

Usage

Note: Below is listedsome of the features, make sure to use--help andautocompletion to learn more of the features as they become available.

Most commands returns a table version of what the Home Assistant API returns.For example to get basic info about your Home Assistant server you useinfo:

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

If you prefer yaml you can use--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

To get list of states you use state list:

$ hass-cli state listENTITY                                                     DESCRIPTION                                     STATEzone.school                                                School                                          zoningzone.home                                                  Andersens                                       zoningsun.sun                                                    Sun                                             below_horizoncamera.babymonitor                                         babymonitor                                     idletimer.timer_office_lights                                                                                  idletimer.timer_small_bathroom                                                                                 idle[...]

You can use--no-headers to suppress the header.

--table-format let you select which table format you want. Default issimple but you can use any of the formats supported byhttps://pypi.org/project/tabulate/:plain,simple,github,grid,fancy_grid,pipe,orgtbl,rst,mediawiki,html,latex,latex_raw,latex_booktabs ortsv

Finally, you can also via--columns control which data you want shown.Each column has a name and a jsonpath. The default setup for entities are:

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

If you for example just wanted the name and all attributes you could do:

$ hass-cli --columns=ENTITY="entity_id,ATTRIBUTES=attributes[*]" state list zoneENTITY             ATTRIBUTESzone.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}

You can get more details about a state by usingyaml orjson outputformat. In this example we use the shorthand of output:-o:

$ hass-cli -o yaml state get light.guestroom_light                                                                                                                                                                       ◼attributes:  friendly_name: Guestroom Light  supported_features: 61context:  id: 84d52fe306ec4895948b546b492702a4  user_id: nullentity_id: light.guestroom_lightlast_changed:'2018-12-10T18:33:51.883238+00:00'last_updated:'2018-12-10T18:33:51.883238+00:00'state:'off'

You can edit state via an editor:

$ hass-cli state edit light.guestroom_light

This will open the current state in your favorite editor and any changes yousave will be used for an update.

You can also explicitly create/edit via the--json flag:

$ hass-cli state edit sensor.test --json='{ "state":"off"}'

List possible services with or without a regular expression filter:

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

For more details the YAML format is useful:

$ hass-cli -o yaml service list homeassistant.togglehomeassistant:  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

You can get history about one or more entities, here getting state changes for the last50 minutes:

$ hass-cli statehistory --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

The data is sorted by default as Home Assistant returns it, thus for history it is usefulto sort by a property:

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

Note: the --sort-by argument is referring to the attribute in the underlyingjson/yaml NOT the column name. The advantage for this is that it canbe used for sorting on any property even if not included in the default output.

Areas and Device Registry

Since v0.87 of Home Assistant there is a notion of Areas in the Device registry.hass-cli letsyou list devices and areas and assign areas to devices.

Listing devices and areas works similar to list Entities.

$ hass-cli device listID                                NAME                           MODEL                            MANUFACTURER        AREAa3852c3c3ebd47d3acac195478ca6f8b  Basement stairs motion         SML001                           Philips             c6c962b892064a218e968fcaee7950c8880a944e74db4bb48ea3db6dd24af357  Basement Light 2               TRADFRI bulb GU10 WS 400lm       IKEA of Sweden      c6c962b892064a218e968fcaee7950c8657c3cc908594479aab819ff80d0c710  Office                         Hue white lamp                   Philips             None[...]$ hass-cli area listID                                NAME295afc88012341ecb897cd12d3fbc6b4  Bathroom9e08d89203804d5db995c3d0d5dbd91b  Winter Garden8816ee92b7b84f54bbb30a68b877e739  Office[...]

You can create and delete areas:

$ 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

You can assign area to a specific device. Here the Kitchenarea gets assigned to device named "Cupboard Light".

$ hass-cli device assign Kitchen"Cupboard Light"

Besides assigning individual devices you can assign in bulk:

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

The above line will assign Kitchen area to all devices with substring "Kitchen Light".

You can also combine individual and matched devices in one line:

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

Above will assign area named "Kitchen" to all devices having substring "Kitchen Light" and tospecific area with id "eab9930..." or named "Cupboard".

Events

You can subscribe and watch all or a specific event type usingevent watch.

$ hass-cli event watch

This will watch for all event types, you can limit to a specific event typeby specifying it as an argument:

$ hass-cli event watch deconz_event

Home Assistant (former Hass.io)

If you are using Home Assistant (former Hass.io) there are commands availablefor you to interact with Home Assistant services/systems. This includes theunderlying services like the supervisor.

Check the Supervisor release you are running:

$ hass-cli ha supervisor inforesult: okdata: version:'217' version_latest:'217' channel: stable [...]

Check the Core release you are using at the moment:

$ hass-cli ha core inforesult: okdata:    version: 0.108.2    version_latest: 0.108.3    [...]

Update Core to the latest available release:

$ hass-cli ha core update

Other

You can call services:

$ hass-cli service call deconz.device_refresh

With arguments:

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

Open a map for your Home Assistant location:

$ hass-cli map

Render templates server side:

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

Render templates client (local) side:

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

Auto-completion

As described above you can usesource <(hass-cli completion zsh) toquickly and easy enable auto completion. If you do it from your.bashrcor.zshrc it's recommend to use the form below as that does not triggera run ofhass-cli itself.

For zsh:

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

For bash:

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

Once enabled there is autocompletion for commands and for certain attributes like entities:

$ 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_2light.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_2light.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[...]

Note: For this to work you'll need to have setup the following environmentvariables if your Home Assistant installation is secured and not running onlocalhost:8123:

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

Help

$ hass-cliUsage: hass-cli [OPTIONS] COMMAND [ARGS]...  Command line interfacefor 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 beset with the                                  environment variable HASS_SERVER.  [default:                                  auto]  --token TEXT                    The Bearer tokenfor Home Assistant                                  instance. Can also beset with the                                  environment variable HASS_TOKEN.  --password TEXT                 The API passwordfor Home Assistant                                  instance. Can also beset with the                                  environment variable HASS_PASSWORD.  --timeout INTEGER               Timeoutfor 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.

Clone the git repository and

$ pip3 install --editable.

Development

Developing is (re)using as much as possible fromHome Assistant development setup.

Recommended way to develop is to use virtual environment to ensure isolationfrom rest of your system using the following steps:

Clone the git repository and do the following:

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

after this you should be able to edit the source code and runninghass-clidirectly:

$ hass-cli
[8]ページ先頭
©2009-2025 Movatter.jp