hass-cli 0.5: Area, Device Reigstry and event CLI

system · February 11, 2019, 9:05am

With Home Assistant 0.87 out we got Areas and Device Registry UI thus it is time to do a release of hass-cli that allows you to operate on these in a terminal.

This release adds the following features:

Area list, create, delete, list and rename
Device list and assign
Event watch

To get it run:

$ pip3 install homeassistant-cli

And once you have configured some of the new things you can like:

Create an area:

$ hass-cli area create Attic
-  id: 1
   type: result
   success: true
   result:
      area_id: 83977bdb16524579a856560925a791a7
      name: Attic

List all your areas:

$ hass-cli area list
ID                                NAME
295afc88012341ecb897cd12d3fbc6b4  Bathroom
9e08d89203804d5db995c3d0d5dbd91b  Winter Garden
8816ee92b7b84f54bbb30a68b877e739  Office
e6ebd3e6f6e04b63a0e4a109b4748584  Kitchen
f7f5412a9f47436da669a537e0c0c10f  Livingroom
bc98c209249f452f8d074e8384780e15  Hallway
83977bdb16524579a856560925a791a7  Attic

List devices matching a pattern:

$ hass-cli device list "Kitchen.*Light*"
ID                                NAME                      MODEL                    MANUFACTURER    AREA
f9cad07069c74d519fbe84811c91f1fb  Kitchen Light 2           LCT003                   Philips         e6ebd3e6f6e04b63a0e4a109b4748584
d02ec64623ae4407a80b903cbc061511  Kitchen Light 3           LCT003                   Philips         e6ebd3e6f6e04b63a0e4a109b4748584
820c9e511fce42ea92b228c18710aa56  Kitchen Light 1           LCT003                   Philips         e6ebd3e6f6e04b63a0e4a109b4748584
417dd42c0c764765aa29580d77b8b7ad  Kitchen Light 5           LCT003                   Philips         e6ebd3e6f6e04b63a0e4a109b4748584

Like with entity list you can filter and pipe results to get interesting things.

How about a inventory count?

$ hass-cli --no-headers --columns manufacturer,model device list | sort | uniq -c | sort -nr
10 IKEA of Sweden      TRADFRI bulb GU10 WS 400lm
 8 Philips             SML001
 7 LUMI                lumi.sensor_magnet.aq2
 6 Sonos               Play:1
 6 Philips             LTW012
 6 Philips             LCT003
 6 Philips             Hue color spot
 6 Philips             Hue ambiance candle
 5 Philips             LWG001
 5 Philips             LCT012
 5 Philips             Hue color candle
 5 IKEA of Sweden      TRADFRI bulb E14 W op/ch 400lm
 4 Sonos               One
 4 Philips             RWL021
 4 Philips             Hue color lamp
 4 IKEA of Sweden      TRADFRI remote control
 3 Philips             Hue lightstrip plus
 3 OSRAM               Color temperature light
 3 LUMI                lumi.vibration.aq1
 3 IKEA of Sweden      TRADFRI transformer 30W
 ....

And then my favorite feature, assign of area to a device:

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

or even more powerful, bulk-assign to any entity matching a certain pattern:

$ hass-cli device assign --match "Kitchen" Kitchen
  Successfully assigned 'Kitchen' to 'Kitchen'
  Successfully assigned 'Kitchen' to 'Kitchen table left'
  Successfully assigned 'Kitchen' to 'Kitchen table right'
  Successfully assigned 'Kitchen' to 'Kitchen left middle at window'
  Successfully assigned 'Kitchen' to 'Kitchen front right at fridge'
  Successfully assigned 'Kitchen' to 'Kitchen left back at hub'
  Successfully assigned 'Kitchen' to 'Kitchen left back at bar'
  Successfully assigned 'Kitchen' to 'Kitchen right back at sink'
  Successfully assigned 'Kitchen' to 'Kitchen right middle at oven'
  Successfully assigned 'Kitchen' to 'Kitchen Light 2'
  Successfully assigned 'Kitchen' to 'Kitchen Light 3'
  ....

And finally as a little bonus feature you can now watch the event bus from the CLI:

All events:

or specific events:

$ hass-cli event watch call_service

At the moment the output is raw JSON, that will improve in a future release.

The full change list including bugfixes from community is as follows:

What’s Changed

New features:

Device, Area and event support 237ade8 @maxandersen
add minimal dockerfile 2b00bd7 Ben Lebherz

Bug fixes:

fix(entity): honor –columns in entity get 67397a1 @maxandersen
Fix result reporting from service calls 14fc952 @maxandersen
Remove pyaml and move to ruamel only for yaml df9f8c2 @maxandersen

Minor fixes:

fix: release 0.5.0 version 200a099 @maxandersen
fix: be pep440 complant 98320f8 @maxandersen
fix: fix lint errors eca26fa @maxandersen
fix: fix lint errors ffd2369 @maxandersen
enable deploy of git timestamped build 4b27a65 @maxandersen
Merge branch ‘master’ into dev caaf7b1 @maxandersen
add docker reference d3b64e8 @maxandersen
docs: add docs for area, device and event watch ee4f74a @maxandersen
Make dockerfile build from source + entrypoint b7f8764 @maxandersen
Fix lint issue 8bb0c9e @fabaff
Fix lint issues 58fdc83 @fabaff
fix bad typing 499b544 @maxandersen
fix editor formatting 86d9bf8 @maxandersen
Fix version 3765a03 @maxandersen
Fix version marker edbe4bf @maxandersen

Have fun!

Max Rydahl Andersen

This is a companion discussion topic for the original entry at https://www.home-assistant.io/blog/2019/02/11/hass-cli-0-dot-5-area-entity-registry-and-event-cli/

defcon · February 11, 2019, 11:08am

links to commits are wrong, they are missing the dash in home-assistant twice.
eg:
https://github.com/homeassistant/homeassistant-cli/…
should be
https://github.com/home-assistant/home-assistant-cli/…

maxandersen · February 11, 2019, 11:51am

dangit - need to check what went wrong there as that part is autogenerated. Thanks!

PR submitted: https://github.com/home-assistant/home-assistant.io/pull/8479

mbonani · February 11, 2019, 1:25pm

This release adds the following features:

Area list , create , delete , list and rename

You have list twice there.

maxandersen · February 11, 2019, 1:56pm

Gdammit. I guess I really should stop writing blogs at midnight

Thanks though.

ronytomen · February 12, 2019, 3:04am

Just discovered the CLI project a few weeks ago! Appreciate the update, works great!

DavidFW1960 · February 12, 2019, 3:20am

Community ssh addon still only 0.4.4… when will it get 0.5?

frenck · February 12, 2019, 6:30am

You are asking the wrong person there. Update for it has been merged, currently testing before release.

maxandersen · February 12, 2019, 11:51am

thanks @frenck

For what it is worth if you are impatient to get latest version of hass-cli then running pip3 install --upgrade homeassistant-cli works in community ssh addon too

rufiik · February 12, 2019, 1:02pm

Does docker image (homeassistant/armhf-homeassistant) already contain cli?

maxandersen · February 12, 2019, 1:43pm

fixed in https://github.com/home-assistant/home-assistant.io/pull/8503

maxandersen · February 12, 2019, 1:46pm

There is no plans for including hass-cli inside the homeassistant docker image as I doesn’t seem to have a good usecase.

You can give https://hub.docker.com/r/homeassistant/home-assistant-cli a try though. That is hass-cli standalone in a docker container you should be able to run anywhere you have access to docker and access to any remote homeassistance instance.

Its planned to be part of 0.6 release thus feedback very welcome.

Info on how to best use it in dev branch at https://github.com/home-assistant/home-assistant-cli#docker

rufiik · February 12, 2019, 1:52pm

OK, thanks, that’s nice having dedicated docker image, just some environment variables are required to setup.
I’ll give it a try for sure

Torbenan · February 13, 2019, 3:28pm

@maxandersen It would be really great if the documentation had a description of, what Area, Divece Registry and event CLI can be used for. I for one havn’t god a clue, what event CLI is. Is this blog post for programmers only or…?

maxandersen · February 13, 2019, 5:30pm

Fully understood. Not everyone is used to use the terminal. And it isn’t necessarily something everyone would like to use.

Does the explanation in the blog above help you at all ? I try and give both simple and more
Advanced examples to illustrate what it can be used for.

And cli = command line interface.

Torbenan · February 14, 2019, 2:20pm

Thanks Max. Continuing in English though we share a different language.
To be honest the documentation does not help at all.
This is a perfect example of the strength at weakness of open source. It’s great you have created a module, but 99,9% of the world population would not have a clue of what it is if the read the blog.

maxandersen · February 14, 2019, 3:56pm

Saying the doc is bad and not understood by 99% is not really making me closer to grokking what you would like to see

Do you know of a command line tool which documentation explains its own usecase better to those who most likely won’t use it ?

In the introduction blog on hass-cli I added a FAQ trying to capture questions I could imagine - https://www.home-assistant.io/blog/2019/02/04/introducing-home-assistant-cli/

does that help ? if yes I can make that more prominent in the docs.

mcnovy · February 22, 2019, 4:55pm

This post is not an introduction to hass-cli, but rather an update to what’s new in version 0.5.
A link to the original introduction could be added to this blog post, though max have added it to the comments.

The documentation for areas etc. Is not really anything specific to hass-cli but rather home assistant 0.87 as Max already states in the first line of this blog post.
So the explanation of areas can be found in the release update post for home assistant 0.87.

In short, hass-cli is a kind of text based interface replacement for the home assistant web interface, And doesn’t really add any features to home assistant, but rather adds some advanced configuration features from a command line interface (CLI), it’s not specific to programmers, but probably rather advanced users and my guess for future troubleshooting between users as troubleshooting commands are easy to share between users.

The documentation for home assistant and hass-cli (and even for a lot of open source) isn’t bad at all.
And this is open source, so everyone can contribute.

BTW. Thanks max, nice work.

gomibushi · March 5, 2019, 8:00am

This is awesome stuff! However I am of the Windows-variety and got a Windows-server running what little other stuff I run. It might be that my google-fu failed me just now, but I can’t seem to find anything regarding running this on Windows. Could it work in bash on windows, cygwin or some way?

And a small Hail Mary: I would of course prefer a full on Powershell module, but yes I do understand hass-cli is not close to that. Just saying, if anyone with the skills feel up to it.

maxandersen · March 7, 2019, 1:10am

I don’t have easy access to a Windows machine at The moment but besides auto completion I would expect it to just work on Windows, if not then please open bug reports.