hctl

hctl is a tool to control your Home Assistant devices from the command line

I needed a tool to quickly control my devices from the command line, focusing on easy to use and short commands to toggle or turn on/off lights, switches or even automations, play a mp3 from my local system, or change the volume of a media player. And here we are!

Features

• Support for Home Assistant
• Turn on/off, or toggle all capable devices
• Set brightness on all capable devices
• Play local and remote music files
• Set volume on media players
• List all Domains & Domain-Services
• Completion for bash, zsh, fish and powershell, auto completing all capable devices
• Add shortcuts/mappings for devices and media files
• Control over short and long names
• Fuzzy matching your devices so you can keep it short

Install

Homebrew

brew tap xx4h/hctl https://github.com/xx4h/hctl
brew install xx4h/hctl/hctl

asdf

asdf plugin add hctl https://github.com/xx4h/asdf-hctl.git
asdf global hctl latest

for more information see asdf-hctl

Go

# version will be the latest tag, but will show version "dev"
go install github.com/xx4h/hctl@latest

Release binary

Download the latest release binary from the Release Page and extract it

Build & Install from Source

git clone https://github.com/xx4h/hctl.git && cd hctl
make build && make local-install # intalls to ~/.local/bin/hctl

Configuration

Wizard

Run the init command

hctl init

Manually

Copy the example config from this project

# Configure Hub
hub:
  type: hass
  url: https://home-assistant.example.com/api
  token: YourToken

ensure the folder does already exist and edit with your favorite editor

mkdir -p ~/.config/hctl
$EDITOR ~/.config/hctl/hctl.yaml

Completion

To really benefit from all features, ensure you've loaded the shell completion

# For bash (e.g. in your ~/.bashrc)
type hctl >/dev/null 2>&1 && source <(hctl completion bash)

For more information on how to setup completion for bash, zsh, fish and PowerShell, see hctl completion -h

Optional Shorten command to a minimum

# this should at least work for bash and zsh
alias h='hctl'
source <(hctl completion bash | sed -e 's/hctl/h/g')

# afterwards toggling `switch.livingroom_warp` (with `Short Names` and `Fuzzy Matching` enabled) can be used like this
h t lw

Usage

# Turn on all lights on Floor 1
hctl on floor1

# Toggle a switch called "some-switch"
hctl toggle some_switch

# Play a local music file
hctl play myplayer ~/path/to/some.mp3

Completion Short Names

Home Assistant names its entities domain.name, like light.some_light.

# Imagine having the following devices/entities
light.livingroom_main
light.livingroom_corner
light.livingroom_other
switch.livingroom_warp

# Completion with Short Names feature enabled will auto complete them like
# e.g. if you want to turn off a switch you remeber starting with "sp"
hctl off li<TAB>
hclt off livingroom_<TAB><TAB>
livingroom_main     livingroom_corner      livingroom_other

# Without Short Names feature enabled they will be completed like
hctl off li<TAB>
hclt off light.<TAB><TAB>
light.livingroom_main     light.livingroom_corner      light.livingroom_other

Completion Short Names can be disabled with:

completion:
  short_names: false

Fuzzy Matching

# Imagine having the following devices
light.livingroom_main
light.livingroom_corner
light.livingroom_other
switch.livingroom_warp

# Turn on device with fuzzy matching (matching "switch.livingroom_warp")
hctl on lw

Fuzzy Matching is enabled by default. Fuzzy Matching can be turned off in the config with:

handling:
  fuzz: false

Device Mapping

# Set shortcut for `light.livingroom_main` to `lm`
hctl config set device_map.lm light.livingroom_main

# Use shortcut
hctl toggle lm
hctl off lm
hctl brightness lm 50

Media Mapping

# Set shortcut for `/home/user/sounds/horn.mp3` to `horn`
hctl config set media_map.horn /home/user/sounds/horn.mp3

# Use shortcut
hctl play player1 horn

What's Next / Roadmap

• Add more actions (like press e.g. Buttons, trigger e.g. Automations, or lock and unlock a Lock)
• Add output/feedback on actions (e.g. use pterm)
• Allow multiple devices on actions
• Add optional positional for list entities, following the same logic as in toggle, on and off (e.g. matching short names and fuzzy matching)
• Add possibility to add local mappings for devices in config
• Add install methods (native, asdf, ...)