Home Assistant

Introducing Home Assistant CLI aka. hass-cli

Max Rydahl Andersen

When I started using Home Assistant (HA) I was missing a way to interact with HA via a command line (CLI). A CLI allows you to utilize the power of auto-completion, scripting and direct access.

Thus I started working on Home Assistant CLI, a project that was initially started by Fabian Affolter.

The great thing about hass-cli is that it uses the exact same API’s as the other UI’s and integration uses thus it makes a great complement to the Home Assistant family of tools.

Last week we released version 0.4, which provides majority of the features I was looking for to do from a CLI.

Feature highlights:

  • Get configuration info (hass-cli config)
  • List, get, edit and delete state for entities (hass-cli entity’)
  • Query history with relative time (‘hass-cli entity history’)
  • List and run services (hass-cli services)
  • Execute templates locally and remotely (hass-cli template)
  • Control over columns, sorting, etc. (hass-cli --columns attr1,attr2 --sort-by attr3)
  • Shell completion for most commands and arguments (hass-cli completion zsh)
  • Get logs (hass-cli system log)
  • Run discovery (hass-cli discover)
  • Show map for zone (hass-cli map)
  • Call raw api directly (hass-cli raw)
  • … and more

Usage

For the basic intro to hass-cli see the docs at github.

Installation

Install latest homeassistant-cli by pip:

$ pip3 install homeassistant-cli

or if upgrade use:

$ pip3 install --upgrade homeassistant-cli

or if you like an isolated install you can use pipsi

$ pipsi install --python python3 homeassistant-cli

or if you are adventurous you can build it from source at.

Changes since 0.1-0.3

The first thing is that the commands have been cleaned up to be more logcial/explicit.

$ hass-cli
...
...
Commands:
completion  Output shell completion code for the specified shell (bash or...
config      Get configuration from a Home Assistant instance.
discover    Discovery for the local network.
entity      Get info and operate on entities from Home Assistant.
event       Interact with events.
info        Get basic info from Home Assistant.
map         Print the current location on a map.
raw         Call the raw API (advanced).
service     Call and work with services.
system      System details and operations for Home Assistant.
template    Render templates on server or locally.

Rather than using generic terms (eg. get, list), the commands are now explicit and have further sub-commands.

The biggest change is that most operations, by default now use “table” mode. i.e., instead of getting a yaml or json dump you get a more concise view:

$ hass-cli entity list winter
ENTITY                           DESCRIPTION                STATE    
timer.timer_winter_garden                                   idle     
group.winter_garden_lights       Winter Garden Lights       off      
group.winter_garden_motionview   winter garden              off      
light.winter_garden_light_2      Winter Garden Light 2      off      
light.winter_garden_light_5      Winter Garden Light 5      off      
light.winter_garden_light_1      Winter Garden Light 1      off      
light.winter_garden_light_3      Winter Garden Light 3      off      
light.winter_garden_light_4      Winter Garden Light 4      off      
media_player.winter_garden       Winter Garden              paused   
sensor.lightlevel_winter_garden  Winter Garden Motion       1.0      
sensor.temperature_winter_garden Winter Garden Temperature  5.0

On top of better tables you can also use --sort-by to sort by an attribute and you can use --columns to control which attributes to show.

You can combine it all and do history querying with things like:

$ hass-cli --sort-by last_changed entity history \
  --since 50m  light.kitchen_light_1 binary_sensor.presence_kitchen
ENTITY                          DESCRIPTION      STATE
binary_sensor.presence_kitchen  Kitchen Motion   off
light.kitchen_light_1           Kitchen Light 1  on
binary_sensor.presence_kitchen  Kitchen Motion   on
binary_sensor.presence_kitchen  Kitchen Motion   off
light.kitchen_light_1           Kitchen Light 1  off

If you still want to get all the glory details you can use -o yaml to get the full details.

Frequently Asked Questions

A few frequent asked questions we’ve seen the last months are as follows:

Why would anyone use this ?

This is not removing or trying to compete with existing ways to access Home Assistant - this is a complementary way to access Home Assistant. If you like to use CLI’s and its power of auto-completion you’ll find hass-cli to be awesome; if not and you prefer the browser UI you just continue using it. We still use it for normal interactions, but when we want to be fast or script things hass-cli is great.

Why not just use the REST API’s directly via curl or similar ?

You can most definitely use curl or similar to access REST API directly - it’s basically what hass-cli does behind the scenes. hass-cli give though a few advantages. Firstly that you do not need to remember the exact commands, hass-cli have contextual help and auto completion to make it super easy to type out. Finally over time as hass-cli will get support for utilizing the more extensive websocket API’s hass-cli will be more consistent and simpler to use than using “raw” access via curl.

Does this only work with HTTPS and hass.io ?

No, it works with any Home Assistant that has REST API exposed - something that is done by default. In short - if you can access Home Assistant with your browser and see the UI hass-cli can communicate and control it too.

Thus http, https, hass.io, non-hass.io, etc. are all supported by hass-cli

Do I need to install Home Assistant to use this ?

No, hass-cli does not require Home Assistant installed on the computer you want to run it on. It should run on any install with Python 3.5 or higher on all major operating systems.

Does this work with client-generated certificates ?

It should, but we have not yet been able to verify it. If you would like to help us try it run with --cert <certificate.pem> and let us know if it works on issue #66.

Next steps

Personally the next feature I would like to add is more specific support for system control commands (like refreshing groups, restarting, etc.) but also for accessing hass.io add-ons. Also having an easy way to hook into the event bus (via websocket) to see what is happening live.

What would you like to see ?

Feedback

If you have questions for feedback you can put a comment on this blog, use the hass-cli forum thread or open issues or pull-requests at github.

Have fun!

Max Rydahl Andersen

[Update: we are wrong] Nest locks users out of their own data

Paulus Schoutsen

Update 1 (Jan 24): We got some reports from people that they are still able to create accounts and generate the right keys. We just verified and this is the case. So for now you can still access your data, which is good. We’re still puzzled on the response to our tweet. And thanks to Reddit user /u/lefos123 for pointing out that they announced this updated link on Nov 2018.

Although it’s still working, we’re still scared about the future of the Nest API.

Some sad news for users with a Nest product: Nest is no longer accepting new developer accounts. This means that if you bought a Nest thermostat, you are no longer able to access YOUR data.

New Home Assistant users will not be able to integrate their Nest products. Home Assistant users that have already integrated Home Assistant with Nest are not affected.

We hope that Nest will implement a new program or add support for locally controlling the Nest thermostat, if they do, we will update this post. Until then, we can no longer recommend buying or using any Nest product.

0.86: New Lovelace UI and Zigbee Management Panel!

Paulus Schoutsen

Today we’re releasing Home Assistant 0.86. And oh wow, this is an amazing release. First awesome thing: the Lovelace user interface, which we’ve been working on for the last 8 months, is now the default in Home Assistant. We have a lot to talk about, so we created a separate blog post just for the Lovelace release here.

Next up, we’ve updated the Home Assistant demo. It’s snappier, it’s snazzier, and best of all: it contains four fully functional Lovelace user interfaces that you can play with! Change the states or go in config mode and add, edit or re-organize the cards. We’ve set it up in such a way now that the demo will be automatically updated with the latest release of Home Assistant, so it will always feature the latest things.

Screenshot of the new demo. Screenshot of Lovelace in the new demo.

Zigbee management panel

This release includes a brand new Zigbee management panel to manage your Zigbee network thanks to the hard work by @dmulcahey with the help of @Adminiuga and @damarco. The new panel makes it easy to:

  • Issue Permit and Remove operations
  • Reconfigure Node, which will rebind and reconfigure the reporting for a device. Which can help solve issues.
  • Reading and setting cluster attributes. This is useful for viewing and setting things such as device sensitivity levels.
  • View and issue cluster commands. Note on this feature: support for commands with arguments is coming soon.

The Zigbee team is also planning a bunch of cool things for 2019. Direct device binding (directly pairing remotes to lights) is already in development and they are planning support for group management as well. Targeted and broadcast joins are also right around the corner (we’re waiting for a new Zigpy release). Exciting times for Zigbee users!

Screenshot of the Zigbee management panel. Screenshot of the Zigbee management panel.

Noteworthy backward-incompatible changes

Update: the entity ID one was too harsh, it’s now a warning.

This release also includes two noteworthy backward-incompatible changes. One is a follow-up on the slugify breaking change from last release. We did not update the validation check for config options that need to be valid slugs. This means that some of your config values might be invalid. Keep an eye at the console as we have a new message to tell you which ones are wrong.

The following things are not allowed in entity IDs:

  • No capital letters
  • No leading or ending underscores
  • No double underscores

This issue also impacts the entity registry, which could contain in some cases invalid entity IDs. Expect entity IDs to change if they contained a double underscore (which becomes 1) or if they started/ended in an underscore (which will be removed).

Another noteworthy breaking change (sorry!), is that the automation time trigger has been split into two: time and time_pattern. If you had a time trigger containing the keys hours, minutes or seconds, update the platform from time to time_pattern.

New Platforms

Release 0.86.1 - January 23

Release 0.86.2 - January 24

Release 0.86.3 - January 26

Release 0.86.4 - January 28

If you need help…

…don’t hesitate to use our very active forums or join us for a little chat. The release notes have comments enabled but it’s preferred if you use the former communication channels. Thanks.

Reporting Issues

Experiencing issues introduced by this release? Please report them in our issue tracker. Make sure to fill in all fields of the issue template.

Read on →

Lovelace UI released!

Paulus Schoutsen

Today we’re happy to announce that our new Lovelace UI, which has been in beta for the last 8 months, is becoming the new default interface of Home Assistant 0.86. With Lovelace we’re taking a new approach to building user interfaces for Home Assistant. We’re no longer storing the look and feel of your UI in your configuration.yaml, requiring restarts for changes. With Lovelace we’re keeping the UI concerns in the UI1, unlocking a whole new set of features:

  • 24 cards to place and configure as you like.
  • UI Editor. A configuration UI to manage your Lovelace UI including live preview when editing cards.
  • Fast. Using a static config allows us to build up the UI once.
  • Customizable.
    • Cards have numerous options to configure how your data is presented.
    • Themes; even at a per card basis.
    • Ability to override names and icons of entities.
    • Custom Cards from our amazing community are fully supported.

In case you’re reading this and want to give it a try right now: we’ve updated the Home Assistant demo. It now features multiple Lovelace configuration examples. The demo is fully interactive, including the configuration UI (accessible via the menu in the top right). You can also access it by updating to Home Assistant 0.86.

For a deep dive into all the new features, check out the latest episode of the Home Assistant podcast, featuring an interview with Zack Arnett from the Lovelace team.

For an overview of all the different features, check out the Lovelace documentation.

1: If you prefer to write your Dashboard config in YAML, Home Assistant also includes an optional YAML mode.

Migrating to Lovelace

You have to do… nothing! If not configured, Lovelace will use the same algorithm to built-up the UI as the old UI did.

History

With Lovelace we’ve built a foundation that not only provides a lean and sleek interface, but will also allow us to add many new exciting features in the future. The main difference with the old UI is that we no longer store any UI concerns in the state machine.

When Home Assistant was started, I came up with an algorithm that would automatically organize the available entities in badges, cards and tabs; and then show that on the screen. Users demanded more influence; so over time, we’ve added a bunch of components and features of the backend whose main or sole purpose were to influence how the algorithm in the UI shows and organizes entities.

As this kept growing, I realized that we were on the wrong path. It was impossible to get an algorithm that would fulfill all needs and the backend shouldn’t be aware of anything in the frontend. It should just deliver the entities and the frontend should figure out how to display things together with the user.

At the same time as this was happening, we also had some discussions about the development of the frontend. Users wanted more control on what is shown, when it’s shown and how it’s shown. Eventually, @andrey-git came up with Custom UI for the old interface. This allowed users to do whatever they wanted. However, it was limited to power users.

Lovelace was built from the start to tackle these problems. The initial version completely dropped the algorithm and required users to add each card to their configuration. We went from a fully automatic UI to nothing. We launched it under the nomer “experimental UI” and it quickly gained traction. People loved the control and the ability to inject custom cards or entity rows at will.

The enthusiasm was great among our power users, however by switching away from an automatic UI, we were no longer beginner-friendly. A new user would open Home Assistant and they would see a blank, unconfigured UI. We realized that this had to be solved if we were to make Lovelace the default.

To solve this, we re-introduced our automatic algorithm. However, this time the algorithm generates a Lovelace configuration. If a user doesn’t like the automatic configuration, they can take control and configure it to their liking. When you take control, the automatic generated configuration will no longer be updated by Home Assistant, allowing the user to change each detail.

To make configuring your UI as easy as possible, Lovelace UI allows (custom) cards to include a config editor. This way the user will be able to quickly edit a card while a live preview shows how the changes look. If a card does not include an editor (yet), the user will be presented with a text editor in the browser.

Because of the ease to customize and share customizations, we’ve already seen a big community get created around Lovelace. They are very active in the #lovelace channel on our chat, and work is shared on ShareTheLove.io and the Lovelace section on Awesome HA.

Credits

Lovelace UI has been 8 months in the making and it has been a big undertaking. We’ve worked hard and are proud of being able to ship this first version. Lovelace UI would not have been possible without the following current and former members of the Lovelace team:

I also want to thank the community for adopting this so eagerly, building a ton of helpful tooling and examples and helping one another to create beautiful UIs for their homes.

Old UI

The transition to Lovelace should be painless for most users. If you are encountering issues, please let us know. For the time being, you will be able to still change back to the old user interface on a per-device basis by going to the info developer tool and following the instructions.

0.85: ESPHome, Plum Lightpad, OpenSenseMap

Paulus Schoutsen

Slugify changed, which can impact entity ID creation if the entities had names with either a - or characters outside of A-Z and the integration has no unique IDs. We now better handle the characters and substitute it with an alternative instead of removing that character.

Read this breaking change warning? 👆 Good. Let’s get started. This is the first release of 2019 and it covers a whopping 4 weeks, as we skipped the last release of the year to focus on friends and family. This is going to be a great year and we’re planning a lot of cool stuff. If you haven’t seen it yet, check the State of the Union to see what we have planned.

We’ve been so good at taking a break, that we pushed Lovelace as the default UI to 86 to make sure it’s super polished. We expect just bug fixes between 85 and 86, so feel free to check it out!

We’re also busy churning through the backlog of open PRs for Home Assistant (170 as of now), if you did a contribution over the past 4 weeks, we’ll get to it soon.

During the break we’ve launched the Home Assistant Data Science Portal. It explains all the data that Home Assistant stores and how you can get a data science environment going to explore it yourself.

This release also features native support for ESPHome, a system for managing ESP8266 and ESP32 microchips with a YAML config inspired by Home Assistant. The native API replaces MQTT for ESPHome firmwares and is designed specifically for Home Assistant and absolute efficiency. 🏎 It also comes with a Hass.io add-on to make configuration even easier.

New Platforms

Release 0.85.1 - January 11

If you need help…

…don’t hesitate to use our very active forums or join us for a little chat. The release notes have comments enabled but it’s preferred if you use the former communication channels. Thanks.

Reporting Issues

Experiencing issues introduced by this release? Please report them in our issue tracker. Make sure to fill in all fields of the issue template.

Read on →

Launched: Data Science Portal

Paulus Schoutsen

Today we are launching our brand new data science portal to teach you how you can learn from your own smart home data. Learn what data Home Assistant stores locally and learn to explore your data. In 15 minutes, you will set up a local data science environment and are running reports on your own data.

We have worked hard on a smooth experience. Single click to set up a local data science environment powered by Jupyter. Pre-installed with our Getting Started notebook for Home Assistant, automatically connects to your database and generates reports with a single click.

All of this is powered by the new JupyterLab hass.io add-on by @frenck and the new HASS Data Detective Python package by @robmarkcole.

Today is only the start. We will continue to develop the data tools for Home Assistant. It’s our goal to make Home Assistant the easiest platform to use for data scientists interested in home automation.

Logitech's stance on local APIs

Paulus Schoutsen

This post originally talked about Logitech not willing to support local APIs after removing their private, but widely used, local API. This decision has been reversed and this blog post is no longer applicable to Logitech. More information on the events can be found in this blogpost.

Logitech has decided to remove a widely used local API of their Logitech Harmony hub. We’ve been tracking the story here. This has caused a lot of commotion among our users, and users of other smart home solutions, that integrated with the Logitech Harmony hub and all of a sudden were surprised with a broken smart home. Not a nice way to start the already busy holiday season!

Since it’s 2018, a lot of these discussions are playing out on Twitter. While browsing the discussions, we came across this statement by a senior manager for product marketing for Logitech Smart Home, Todd Walker:

We have a lot of opinions about this, but felt that they were appropriately covered by Twitter user, and contributor to Home Assistant, Jon Maddox:

[Update: resolved, API reinstated and commitment to keep it around] Logitech Harmony removes local API

Paulus Schoutsen

Update 6 (21 dec): Great news! Logitech has announced in a forum post that it has introduced an XMPP Beta Program that makes it possible to install a developer firmware version which reinstates the XMPP API as it was, including the security vulnerabilties. Note that installing this version voids your warranty.

Logitech is also working on a new version of the hub firmware that fixes the vulnerabilities. This is great and this restores our trust in Logitech. Thanks Logitech for turning around and working with your users.

Screenshot of the developer-only firmware reinstating the local XMPP API. Also includes a disclaimer that it voids your warranty. The developer-only firmware that reinstates the local XMPP API. Voids warranty if installed.

Tenable, the cyber security firm that discovered the security vulnerabilities, has released a Research Advisory detailing the issues and the disclosure timeline.

Update 7 (21 dec): Even better news! Someone from Harmony posted in our forums and stated that they are now committed to maintaining their local XMPP API.

We will verify with Logitech if this post is official, and if so, we will revert the Home Assistant implementation back to using the XMPP API. Until then, we don’t expect the websocket API that we are using since 0.84.3 to go away or change until we migrate back, so if your Harmony setup works today, don’t change anything. (Verified, it’s from an account connected to a logitech.com email address)

Screenshot of someone from Harmony stating that they are going to keep the local XMPP API around. Forum post by Harmony employee on the Home Assistant forums.

Original Post:

Read on →

0.84: Cloud webhooks, Wunderlist and USGS Earth Quakes

Paulus Schoutsen

Time for the last release of the year. We were hoping to end the year with an enormous bang and make Lovelace the default UI. However, in our final stretch we realized that to get to the experience that we wanted, we had to make more last minute changes than we felt comfortable making. If you are a Lovelace tester, please read the section for existing testers below.

We want to wish everybody happy holidays and want to thank all our contributors to the code, the documentation and all the ones in the chat for making up our amazing community. We had a great year with a lot of accomplishments and are looking forward to see all the great stuff you all come up with in 2019. Cheers! 🥂

Paulus

We will skip our next release in our bi-weekly release cycle and plan to be back on January 9. See you then!

Cloud webhooks

This release introduces a new Home Assistant Cloud feature available: cloud webhooks. With cloud webhooks you can enable any webhook-enabled integration or automation in Home Assistant to be accessible via a unique URL in the cloud without having to open up a port on your router.

This means that you can send any data back to your instance for OwnTracks, IFTTT or an automation with a webhook-trigger. Check the cloud page in the configuration panel to get started or read more about the new functionality at the Nabu Casa website.

Improved state restoring

We have a new more reliable way of state restoration introduced by @armills. Instead of relying on the database it will now leverage the storage helper to keep track of states that need to be tracked. This should improve reliability and startup speed.

This comes with a downside: we will be unable to restore states the first time you start 0.84.

This means that on upgrade to 0.84 any automation that doesn’t have an initial_state defined will be disabled.

Improved service calling

We have improved how we call services with better validation checks. This means that if you have an automation or a script that sends invalid data, we will now stop the execution and be better able to point out where your incorrect calls are coming from.

For existing Lovelace testers

If you are currently testing Lovelace, please read the notes thoroughly as a lot has changed. First, we now have now three different Lovelace modes: auto-generated, storage, and yaml (the old way of doing Lovelace). The UI editor will be limited to the storage mode, in which we control how the config is stored.

So if you were using Lovelace before 0.84, you now have two options. Option one is to use the new storage mode and import your existing file. You can do this by opening the Lovelace UI and click on Configure UI, this will prompt you to change to storage mode. This will unlock a new option in the menu called “raw config editor”. Open this and paste the content of your ui-lovelace.yaml file into it and click save. Note that YAML comments are not persisted and !include/!secret are not supported if in storage mode.

If you want to continue managing a YAML file, check here how to enable the YAML mode. The file ui-lovelace.yaml will now follow the same options as configuration.yaml. This means that the Lovelace YAML config is now parsed with YAML 1.1 instead of YAML 1.2. Major change is that you need to make sure that you wrap on and off with quotes in your configs!

We have also aligned the configuration of all the cards, causing backward-incompatible changes. Changes are especially focused around how we define actions for short and long presses. See the docs for more info.

Editor UI is now further processed. You can manage your Lovelace UI without leaving your browser! It is possible to add, edit and delete views. It is possible to add, edit, move and delete cards, including custom cards!

New Platforms

Release 0.84.1 - December 12

Release 0.84.2 - December 14

Release 0.84.3 - December 17

Release 0.84.4 - December 19

Release 0.84.5 - December 19

  • Fix Harmony for people not running Home Assistant in Docker (@ehendrix23)

Release 0.84.6 - December 21

  • Fix incorrect local check when creating webhooks via a config flow (impacted all but Owntracks) (@balloob - #19494)

Frontend

If you need help…

…don’t hesitate to use our very active forums or join us for a little chat. The release notes have comments enabled but it’s preferred if you use the former communication channels. Thanks.

Reporting Issues

Experiencing issues introduced by this release? Please report them in our issue tracker. Make sure to fill in all fields of the issue template.

Read on →

0.83: Fibaro Home Center Hubs, locks via voice, Traccar

Paulus Schoutsen

It’s release day! Today we’re happy to release Home Assistant 0.83. If you might have noticed, this is using our new release schedule which evolves around releases on Wednesdays instead of Fridays (this one is one day late). It’s the same 2-week release schedule as before, except that it has moved 5 days later.

So what’s new? A LOT. First, a contributor milestone. This release the backend has 99 contributors. That means that in the last 2,5 weeks since the last release, 99 people have written code that is now part of Home Assistant. The frontend has another 15 contributors. It’s amazing to see how as a community we can rally around building the best piece of home automation software out there and get it done.

I want to give a shout out to @MartinHjelmare who is doing an amazing job going through PRs and helping out where possible. Good job! ✨

Alright, time for some highlights. First is that thanks to @pbalogh77, Fibaro Home Center hubs are now supported. If you had already invested in a Z-Wave network with Fibaro, you can now seamlessly integrate that into Home Assistant and combine it with all the other intgrations out there.

The second cool thing is that Google Assistant now supports locks. Locking is enabled by default, but if you want to support unlocking, you will need to go to the Home Assistant Cloud settings to enable unlocking, or, if you’re using the manual config, add allow_unlock: true to your config.

Screenshot of the Google Assistant card on the cloud panel. See what entities are exposed to Google and enable unlocking of locks.

The frontend team hasn’t sit still either. The extended release notes are here but the main highlight is the new shopping list card. @iantrich took the shopping list panel and shrunk it to the size of a Lovelace card.

Oh and if you’re into GPS tracking: OwnTracks is a lot easier to get started with in this release. But if you really like all the data in the world: @ludeeus has added support for Traccar, including accompanying Hass.io add-on by @frenck.

Note, this release includes a migration to add an index to speed up the logbook queries. It might take a bit on first boot, please be patient.

New Platforms

Release 0.83.1 - November 29

Release 0.83.2 - November 30

Release 0.83.3 - December 3

We had an issue where users that are still using the legacy auth for API access but not for UI access could end up with a legacy auth user without any permissions. If you run into this issue, we suggest to upgrade your scripts to use long lived access tokens, which offer the exact same functionality. Alternative is that you manually upgrade the legacy API user to be part of the admin group using these instructions.

If you need help…

…don’t hesitate to use our very active forums or join us for a little chat. The release notes have comments enabled but it’s preferred if you use the former communication channels. Thanks.

Reporting Issues

Experiencing issues introduced by this release? Please report them in our issue tracker. Make sure to fill in all fields of the issue template.

Read on →