Package: homeassistant-cli
Home Assistant Command-line Interface (hass-cli)The Home Assistant Command-line interface (hass-cli) allows one to
work with a local or a remoteHome AssistantCore or Home Assistant (former Hass.io) instance directly from the command-line.InstallationTo use latest release:$pipinstallhomeassistant-cliTo use latest pre-release fromdevbranch:$pipinstallgit+https://github.com/home-assistant-ecosystem/home-assistant-cli@devThe developers ofhass-cliusually provide up-to-datepackagesfor recent Fedora and EPEL releases. Usednffor the installation:$sudodnf-yinstallhome-assistant-cliThe community is providing support for macOS throughhomebew.$brewinstallhomeassistant-cliKeep in mind that the available releases in the distribution could be out-dated.home-assistant-cliis also available for NixOS.To use the tool on NixOS. Keep in mind that the latest release could only
be available in theunstablechannel.$nix-env-iAnixos.home-assistant-cliDockerIf you do not have a Python setup you can try usehass-clivia a container
using Docker.$dockerrunhomeassistant/home-assistant-cliTo make auto-completion and access environment work like other scripts you’ll
need to create a script file to execute.$curlhttps://raw.githubusercontent.com/home-assistant/home-assistant-cli/master/docker-hass-cli>hass-cli$chmod+xhass-cliNow put thehass-cliscript into your path and you can use it like if you
had installed it via command line as long as you don’t need file system access
(like forhass-clitemplate).SetupTo get started you’ll need to have or generate a long lasting token format
on your Home Assistant profile page (i.e.https://localhost:8123/profilethen scroll down to “Long-Lived Access Tokens”).Then you can use--serverand--tokenparameter on each call or as is
recommended setupHASS_SERVERandHASS_TOKENenvironment variables.$exportHASS_SERVER=https://homeassistant.local:8123$exportHASS_TOKEN=<secret>Once that is enabled, run one of the following commands to enable
autocompletion forhass-clicommands.$source<(_HASS_CLI_COMPLETE=bash_sourcehass-cli)# for bash$source<(_HASS_CLI_COMPLETE=zsh_sourcehass-cli)# for zsh$eval(_HASS_CLI_COMPLETE=fish_sourcehass-cli)# for fishUsageNote: Below is listedsomeof the features, make sure to use--helpand
autocompletion 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-cliinfoBASE_URLLOCATIONREQUIRES_API_PASWORDVERSIONhttps://home-assistant.local:8123FortofSolitudeFalse0.86.2If you prefer yaml you can use--output=yaml:$hass-cli--outputyamlinfobase_url:https://home-assistant.local:8123location_name:WayneManorrequires_api_password:falseversion:0.86.2To get list of states you usestate list:$hass-clistatelistENTITYDESCRIPTIONSTATEzone.schoolSchoolzoningzone.homeAndersenszoningsun.sunSunbelow_horizoncamera.babymonitorbabymonitoridletimer.timer_office_lightsidletimer.timer_small_bathroomidle[...]You can use--no-headersto suppress the header.--table-formatlet you select which table format you want. Default issimplebut 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_booktabsortsvFinally, you can also via--columnscontrol 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_changedIf you for example just wanted the name and all attributes you could do:$hass-cli--columns=ENTITY="entity_id,ATTRIBUTES=attributes[*]"statelistzoneENTITYATTRIBUTESzone.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 usingyamlorjsonoutput
format. In this example we use the shorthand of output:-o:$hass-cli-oyamlstategetlight.guestroom_light◼attributes:friendly_name:GuestroomLightsupported_features:61context:id:84d52fe306ec4895948b546b492702a4user_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-clistateeditlight.guestroom_lightThis will open the current state in your favorite editor and any changes you
save will be used for an update.You can also explicitly create/edit via the--jsonflag:$hass-clistateeditsensor.test--json='{ "state":"off"}'List possible services with or without a regular expression filter:$hass-cliservicelist'home.*toggle'DOMAINSERVICEDESCRIPTIONhomeassistanttoggleGenericservicetotoggledeviceson/off...For more details the YAML format is useful:$hass-cli-oyamlservicelisthomeassistant.togglehomeassistant:services:toggle:description:Genericservicetotoggledeviceson/offunderanydomain.Sameusageasthelight.turn_on,switch.turn_on,etc.services.fields:entity_id:description:Theentity_idofthedevicetotoggleon/off.example:light.living_roomYou can get history about one or more entities, here getting state changes for the last
50 minutes:$hass-clistatehistory--since50mlight.kitchen_light_1binary_sensor.presence_kitchenENTITYDESCRIPTIONSTATECHANGEDbinary_sensor.presence_kitchenKitchenMotionoff2019-01-27T23:19:55.322474+00:00binary_sensor.presence_kitchenKitchenMotionon2019-01-27T23:21:44.015071+00:00binary_sensor.presence_kitchenKitchenMotionoff2019-01-27T23:22:02.330566+00:00light.kitchen_light_1KitchenLight1on2019-01-27T23:19:55.322474+00:00light.kitchen_light_1KitchenLight1off2019-01-27T23:36:45.254266+00:00The data is sorted by default as Home Assistant returns it, thus for history it is useful
to sort by a property:$hass-cli--sort-bylast_changedstatehistory--since50mlight.kitchen_light_1binary_sensor.presence_kitchenENTITYDESCRIPTIONSTATECHANGEDbinary_sensor.presence_kitchenKitchenMotionoff2019-01-27T23:18:00.717611+00:00light.kitchen_light_1KitchenLight1on2019-01-27T23:18:00.717611+00:00binary_sensor.presence_kitchenKitchenMotionon2019-01-27T23:18:12.135015+00:00binary_sensor.presence_kitchenKitchenMotionoff2019-01-27T23:18:30.417064+00:00light.kitchen_light_1KitchenLight1off2019-01-27T23:36:45.254266+00:00Note: the–sort-byargument is referring to the attribute in the underlyingjson/yamlNOT the column name. The advantage for this is that it can
be used for sorting on any property even if not included in the default output.Areas and Device RegistrySince v0.87 of Home Assistant there is a notion of Areas in the Device registry.hass-clilets
you list devices and areas and assign areas to devices.Listing devices and areas works similar to list Entities.$hass-clidevicelistIDNAMEMODELMANUFACTURERAREAa3852c3c3ebd47d3acac195478ca6f8bBasementstairsmotionSML001Philipsc6c962b892064a218e968fcaee7950c8880a944e74db4bb48ea3db6dd24af357BasementLight2TRADFRIbulbGU10WS400lmIKEAofSwedenc6c962b892064a218e968fcaee7950c8657c3cc908594479aab819ff80d0c710OfficeHuewhitelampPhilipsNone[...]$hass-cliarealistIDNAME295afc88012341ecb897cd12d3fbc6b4Bathroom9e08d89203804d5db995c3d0d5dbd91bWinterGarden8816ee92b7b84f54bbb30a68b877e739Office[...]You can create and delete areas:$hass-cliareadelete"Old Shed"-id:1type:resultsuccess:trueresult:success$hass-cliareacreate"New Shed"-id:1type:resultsuccess:trueresult:area_id:cdd09a80f03a4cc59d2943053c0414c0name:NewShedYou can assign area to a specific device. Here the Kitchen
area gets assigned to device named “Cupboard Light”.$hass-clideviceassignKitchen"Cupboard Light"Besides assigning individual devices you can assign in bulk:$hass-clideviceassignKitchen--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-clideviceassignKitchen--match"Kitchen Light"eab9930f8652408882cc8cb604651c60CupboardAbove will assign area named “Kitchen” to all devices having substring “Kitchen Light” and to
specific area with id “eab9930…” or named “Cupboard”.EventsYou can subscribe and watch all or a specific event type usingevent watch.$hass-clieventwatchThis will watch for all event types, you can limit to a specific event type
by specifying it as an argument:$hass-clieventwatchdeconz_eventHome Assistant (former Hass.io)If you are using Home Assistant (former Hass.io) there are commands available
for you to interact with Home Assistant services/systems. This includes the
underlying services like the supervisor.Check the Supervisor release you are running:$hass-clihasupervisorinforesult:okdata:version:'217'version_latest:'217'channel:stable[...]Check the Core release you are using at the moment:$hass-clihacoreinforesult:okdata:version:0.108.2version_latest:0.108.3[...]Update Core to the latest available release:$hass-clihacoreupdateOtherYou can call services:$hass-cliservicecalldeconz.device_refreshWith arguments:$hass-cliservicecallhomeassistant.toggle--argumentsentity_id=light.office_lightOpen a map for your Home Assistant location:$hass-climapRender templates server side:$hass-clitemplatemotionlight.yaml.j2motiondata.yamlRender templates client (local) side:$hass-clitemplate--locallovelace-template.yamlAuto-completionAs described above you can usesource<(hass-clicompletion zsh)to
quickly and easy enable auto completion. If you do it from your.bashrcor.zshrcit’s recommend to use the form below as that does not trigger
a run ofhass-cliitself.For zsh:eval"$(_HASS_CLI_COMPLETE=source_zshhass-cli)"For bash:eval"$(_HASS_CLI_COMPLETE=sourcehass-cli)"Once enabled there is autocompletion for commands and for certain attributes like entities:$hass-clistategetlight.<TAB>⏎✱◼light.kitchen_light_5light.office_lightlight.basement_light_4light.basement_light_9light.dinner_table_light_4light.winter_garden_light_2light.kitchen_light_2light.kitchen_table_light_1light.hallroom_light_2light.basement_light_5light.basement_light_10light.dinner_table_wall_lightlight.winter_garden_light_4light.kitchen_table_light_2light.kitchen_light_1light.hallroom_light_1light.basement_light_6light.small_bathroom_lightlight.dinner_table_light_5light.winter_garden_light_3light.kitchen_light_4[...]Note: For this to work you’ll need to have setup the following environment
variables if your Home Assistant installation is secured and not running on
localhost:8123:exportHASS_SERVER=http://homeassistant.local:8123exportHASS_TOKEN=eyJ0eXAiO-----------------------ed8mj0NP8Help$hass-cliUsage:hass-cli[OPTIONS]COMMAND[ARGS]...CommandlineinterfaceforHomeAssistant.Options:-l,--loglevelLVLEitherCRITICAL,ERROR,WARNING,INFOorDEBUG--versionShowtheversionandexit.-s,--serverTEXTTheserverURLor`auto`forautomaticdetection.CanalsobesetwiththeenvironmentvariableHASS_SERVER.[default:auto]--tokenTEXTTheBearertokenforHomeAssistantinstance.CanalsobesetwiththeenvironmentvariableHASS_TOKEN.--passwordTEXTTheAPIpasswordforHomeAssistantinstance.CanalsobesetwiththeenvironmentvariableHASS_PASSWORD.--timeoutINTEGERTimeoutfornetworkoperations.[default:5]-o,--output[json|yaml|table|ndjson|auto]Outputformat.[default:auto]-v,--verboseEnablesverbosemode.-xPrintbacktraceswhenexceptionoccurs.--certTEXTPathtoclientcertificatefile(.pem)tousewhenconnecting.--insecureIgnoreSSLCertificates.Allowtoconnecttoserverswithself-signedcertificates.Becareful!--debugEnablesdebugmode.--columnsTEXTCustomcolumnskey=valuelist.Example:ENTITY=entity_id,NAME=attributes.friendly_name--no-headersWhenprintingtablesdon'tuseheaders(default:printheaders)--table-formatTEXTWhichtableformattouse.--sort-byTEXTSorttablebythejsonpathexpression.Example:last_changed--helpShowthismessageandexit.Commands:areaGetinfoandoperateonareasfromHomeAssistant...completionOutputshellcompletioncodeforthespecifiedshell(bashor...configGetconfigurationfromaHomeAssistantinstance.deviceGetinfoandoperateondevicesfromHomeAssistant...discoverDiscoveryforthelocalnetwork.entityGetinfoonentitiesfromHomeAssistant.eventInteractwithevents.haHomeAssistant(formerHass.io)commands.infoGetbasicinfofromHomeAssistant.mapShowthelocationoftheconfigoranentityonamap.rawCalltherawAPI(advanced).serviceCallandworkwithservices.stateGetinfoonentitystatefromHomeAssistant.systemSystemdetailsandoperationsforHomeAssistant.templateRendertemplatesonserverorlocally.Clone the git repository and$pip3install--editable.DevelopmentDeveloping is (re)using as much as possible from
[Home Assistant development setup](https://developers.home-assistant.io/docs/en/development_environment.html).Recommended way to develop is to use virtual environment to ensure isolation
from rest of your system using the following steps:Clone the git repository and do the following:$python3-mvenv.$sourcebin/activate$script/setupafter this you should be able to edit the source code and runninghass-clidirectly:$hass-cli