https://github.com/xx4h/hctl
⌨️ 🏠 A tool to control your Home Assistant devices from the command-line
https://github.com/xx4h/hctl
cli cmd command-line command-line-tool ctl hacktoberfest home-assistant homeassistant
Last synced: 10 months ago
JSON representation
⌨️ 🏠 A tool to control your Home Assistant devices from the command-line
- Host: GitHub
- URL: https://github.com/xx4h/hctl
- Owner: xx4h
- License: apache-2.0
- Created: 2024-09-30T17:34:52.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-06T12:35:32.000Z (11 months ago)
- Last Synced: 2025-03-27T00:13:52.093Z (11 months ago)
- Topics: cli, cmd, command-line, command-line-tool, ctl, hacktoberfest, home-assistant, homeassistant
- Language: Go
- Homepage:
- Size: 331 KB
- Stars: 65
- Watchers: 3
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# hctl
[](https://github.com/xx4h/hctl/actions/workflows/linter-full.yml)
[](https://github.com/xx4h/hctl/actions/workflows/test-full.yml)
[](https://github.com/xx4h/hctl/releases)
[](https://goreportcard.com/report/github.com/xx4h/hctl)
[](https://codebeat.co/projects/github-com-xx4h-hctl-main)
[](#)
[](#)
[](#)
[](LICENSE)
[](https://github.com/xx4h/hctl/tags)
[](https://github.com/xx4h/hctl/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/xx4h/hctl/pulls?q=is%3Apr+is%3Aclosed)
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
- Set temperature on capable devices
- 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
```bash
brew tap xx4h/hctl https://github.com/xx4h/hctl
brew install xx4h/hctl/hctl
```
### asdf
```bash
asdf plugin add hctl https://github.com/xx4h/asdf-hctl.git
asdf global hctl latest
```
for more information see [asdf-hctl](https://github.com/xx4h/asdf-hctl)
### Go
```bash
# 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](https://github.com/xx4h/hctl/releases/latest) and extract it
### Build & Install from Source
```bash
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
```bash
hctl init
```
### Manually
Copy the example config from this project
```yaml
# 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
```bash
mkdir -p ~/.config/hctl
$EDITOR ~/.config/hctl/hctl.yaml
```
## Completion
To really benefit from all features, ensure you've loaded the shell completion
```bash
# 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
```bash
# 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
```bash
# 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`.
```bash
# 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
hclt off livingroom_
livingroom_main livingroom_corner livingroom_other
# Without Short Names feature enabled they will be completed like
hctl off li
hclt off light.
light.livingroom_main light.livingroom_corner light.livingroom_other
```
Completion Short Names can be disabled with:
```yaml
completion:
short_names: false
```
### Fuzzy Matching
```bash
# 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:
```yaml
handling:
fuzz: false
```
### Device Mapping
```bash
# 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
```bash
# 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)
- [x] 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)
- [x] Add possibility to add local mappings for devices in config
- [ ] Add install methods (native, asdf, ...)