{"id":17530944,"url":"https://github.com/xx4h/hctl","last_synced_at":"2026-03-27T20:54:25.749Z","repository":{"id":257890659,"uuid":"865536880","full_name":"xx4h/hctl","owner":"xx4h","description":"⌨️ 🏠 A tool to control your Home Assistant devices from the command-line","archived":false,"fork":false,"pushed_at":"2025-03-06T12:35:32.000Z","size":339,"stargazers_count":65,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-27T00:13:52.093Z","etag":null,"topics":["cli","cmd","command-line","command-line-tool","ctl","hacktoberfest","home-assistant","homeassistant"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xx4h.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-30T17:34:52.000Z","updated_at":"2025-03-06T13:43:14.000Z","dependencies_parsed_at":"2024-10-16T22:40:51.830Z","dependency_job_id":"401e841a-febe-4ee0-90af-2b67f617e7f9","html_url":"https://github.com/xx4h/hctl","commit_stats":{"total_commits":96,"total_committers":2,"mean_commits":48.0,"dds":0.01041666666666663,"last_synced_commit":"fc9c13f60efb7e6c1af8667b0d527ba68e9ff041"},"previous_names":["xx4h/hctl"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xx4h%2Fhctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xx4h%2Fhctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xx4h%2Fhctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xx4h%2Fhctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xx4h","download_url":"https://codeload.github.com/xx4h/hctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248686229,"owners_count":21145446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cmd","command-line","command-line-tool","ctl","hacktoberfest","home-assistant","homeassistant"],"created_at":"2024-10-20T17:06:01.628Z","updated_at":"2026-03-27T20:54:25.713Z","avatar_url":"https://github.com/xx4h.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hctl\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/xx4h/hctl\"\u003e\n  \u003cimg alt=\"GitHub forks\" src=\"https://img.shields.io/github/forks/xx4h/hctl\"\u003e\n\u003c/p\u003e\n\n\u003c!-- markdownlint-disable no-empty-links --\u003e\n\n[![Lint Code Base](https://github.com/xx4h/hctl/actions/workflows/linter-full.yml/badge.svg)](https://github.com/xx4h/hctl/actions/workflows/linter-full.yml)\n[![Test Code Base](https://github.com/xx4h/hctl/actions/workflows/test-full.yml/badge.svg)](https://github.com/xx4h/hctl/actions/workflows/test-full.yml)\n[![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/xx4h/hctl/total)](https://github.com/xx4h/hctl/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/xx4h/hctl?)](https://goreportcard.com/report/github.com/xx4h/hctl)\n[![codebeat badge](https://codebeat.co/badges/21ee1b92-b94c-4425-a600-b01dd4b1c045)](https://codebeat.co/projects/github-com-xx4h-hctl-main)\n[![SLOC](https://tokei.rs/b1/github/xx4h/hctl?category=code\u0026style=flat)](#)\n[![Number of programming languages used](https://img.shields.io/github/languages/count/xx4h/hctl)](#)\n[![Top programming languages used](https://img.shields.io/github/languages/top/xx4h/hctl)](#)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n[![Latest tag](https://img.shields.io/github/v/tag/xx4h/hctl)](https://github.com/xx4h/hctl/tags)\n[![Closed issues](https://img.shields.io/github/issues-closed/xx4h/hctl?color=success)](https://github.com/xx4h/hctl/issues?q=is%3Aissue+is%3Aclosed)\n[![Closed PRs](https://img.shields.io/github/issues-pr-closed/xx4h/hctl?color=success)](https://github.com/xx4h/hctl/pulls?q=is%3Apr+is%3Aclosed)\n\u003cbr\u003e\n\n\u003c!-- markdownlint-enable no-empty-links --\u003e\n\nhctl is a tool to control your Home Assistant devices from the command line\n\nI 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.\nAnd here we are!\n\n## Features\n\n\u003cp align=\"center\"\u003e\u003cimg alt=\"hctl showcase demo\" src=\"/assets/demo.gif?raw=true\"/\u003e\u003c/p\u003e\n\n- Support for Home Assistant\n- Turn on/off, or toggle all capable devices\n- Set brightness on all capable devices\n- Play local and remote music files\n- Set volume on media players\n- Set temperature on capable devices\n- List all Domains \u0026 Domain-Services\n- Completion for `bash`, `zsh`, `fish` and `powershell`, auto completing all capable devices\n- Add shortcuts/mappings for devices and media files\n- Control over short and long names\n- Fuzzy matching your devices so you can keep it short\n\n## Install\n\n### Homebrew\n\n```bash\nbrew tap xx4h/hctl https://github.com/xx4h/hctl\nbrew install xx4h/hctl/hctl\n```\n\n### asdf\n\n```bash\nasdf plugin add hctl https://github.com/xx4h/asdf-hctl.git\nasdf global hctl latest\n```\n\nfor more information see [asdf-hctl](https://github.com/xx4h/asdf-hctl)\n\n### Go\n\n```bash\n# version will be the latest tag, but will show version \"dev\"\ngo install github.com/xx4h/hctl@latest\n```\n\n### Release binary\n\nDownload the latest release binary from the [Release Page](https://github.com/xx4h/hctl/releases/latest) and extract it\n\n### Build \u0026 Install from Source\n\n```bash\ngit clone https://github.com/xx4h/hctl.git \u0026\u0026 cd hctl\nmake build \u0026\u0026 make local-install # intalls to ~/.local/bin/hctl\n```\n\n## Configuration\n\n### Wizard\n\nRun the init command\n\n```bash\nhctl init\n```\n\n### Manually\n\nCopy the example config from this project\n\n```yaml\n# Configure Hub\nhub:\n  type: hass\n  url: https://home-assistant.example.com/api\n  token: YourToken\n```\n\nensure the folder does already exist and edit with your favorite editor\n\n```bash\nmkdir -p ~/.config/hctl\n$EDITOR ~/.config/hctl/hctl.yaml\n```\n\n## Completion\n\nTo really benefit from all features, ensure you've loaded the shell completion\n\n```bash\n# For bash (e.g. in your ~/.bashrc)\ntype hctl \u003e/dev/null 2\u003e\u00261 \u0026\u0026 source \u003c(hctl completion bash)\n```\n\nFor more information on how to setup completion for `bash`, `zsh`, `fish` and `PowerShell`, see `hctl completion -h`\n\n**Optional**\nShorten command to a minimum\n\n```bash\n# this should at least work for bash and zsh\nalias h='hctl'\nsource \u003c(hctl completion bash | sed -e 's/hctl/h/g')\n\n# afterwards toggling `switch.livingroom_warp` (with `Short Names` and `Fuzzy Matching` enabled) can be used like this\nh t lw\n```\n\n## Usage\n\n```bash\n# Turn on all lights on Floor 1\nhctl on floor1\n\n# Toggle a switch called \"some-switch\"\nhctl toggle some_switch\n\n# Play a local music file\nhctl play myplayer ~/path/to/some.mp3\n```\n\n### Completion Short Names\n\nHome Assistant names its entities `domain.name`, like `light.some_light`.\n\n```bash\n# Imagine having the following devices/entities\nlight.livingroom_main\nlight.livingroom_corner\nlight.livingroom_other\nswitch.livingroom_warp\n\n# Completion with Short Names feature enabled will auto complete them like\n# e.g. if you want to turn off a switch you remeber starting with \"sp\"\nhctl off li\u003cTAB\u003e\nhclt off livingroom_\u003cTAB\u003e\u003cTAB\u003e\nlivingroom_main     livingroom_corner      livingroom_other\n\n# Without Short Names feature enabled they will be completed like\nhctl off li\u003cTAB\u003e\nhclt off light.\u003cTAB\u003e\u003cTAB\u003e\nlight.livingroom_main     light.livingroom_corner      light.livingroom_other\n```\n\nCompletion Short Names can be disabled with:\n\n```yaml\ncompletion:\n  short_names: false\n```\n\n### Fuzzy Matching\n\n```bash\n# Imagine having the following devices\nlight.livingroom_main\nlight.livingroom_corner\nlight.livingroom_other\nswitch.livingroom_warp\n\n# Turn on device with fuzzy matching (matching \"switch.livingroom_warp\")\nhctl on lw\n```\n\nFuzzy Matching is enabled by default.\nFuzzy Matching can be turned off in the config with:\n\n```yaml\nhandling:\n  fuzz: false\n```\n\n### Device Mapping\n\n```bash\n# Set shortcut for `light.livingroom_main` to `lm`\nhctl config set device_map.lm light.livingroom_main\n\n# Use shortcut\nhctl toggle lm\nhctl off lm\nhctl brightness lm 50\n```\n\n### Media Mapping\n\n```bash\n# Set shortcut for `/home/user/sounds/horn.mp3` to `horn`\nhctl config set media_map.horn /home/user/sounds/horn.mp3\n\n# Use shortcut\nhctl play player1 horn\n```\n\n## What's Next / Roadmap\n\n- [ ] Add more actions (like `press` e.g. Buttons, `trigger` e.g. Automations, or `lock` and `unlock` a Lock)\n- [x] Add output/feedback on actions (e.g. use pterm)\n- [ ] Allow multiple devices on actions\n- [ ] Add optional positional for `list entities`, following the same logic as in `toggle`, `on` and `off` (e.g. matching short names and fuzzy matching)\n- [x] Add possibility to add local mappings for devices in config\n- [ ] Add install methods (native, asdf, ...)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxx4h%2Fhctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxx4h%2Fhctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxx4h%2Fhctl/lists"}