This is the abridged developer documentation for Go Automate # Go Automate > Run common tasks and trigger Home Assistant from anywhere. Go Automate is a small command-line utility that runs common tasks and triggers automations in your home. Bind its commands to keyboard shortcuts or patched apps to control [Home Assistant](https://www.home-assistant.io) instantly. ## Features [Section titled “Features”](#features) Control Home Assistant Turn lights, switches and input booleans on, off or toggle them, and announce to assist satellites, all from the command line. Shortcut-Driven Automations Bind commands to keyboard shortcuts or patched apps to fire automations the moment you press a key. Shared Local Bridge A background bridge keeps a single WebSocket connection to Home Assistant, so watchers and status bars stay cheap on the network. Watch Entities Stream entity state changes live, with stable JSON output for status bars and shell modules. Desktop Notifications Send desktop notifications through `notify-send` from scripts and automations. Interactive TUI A searchable terminal menu launches automatically in an interactive terminal, with every command a keystroke away. ## Home Assistant [Section titled “Home Assistant”](#home-assistant) Lights Turn on, turn off or toggle any light entity. Switches Turn on, turn off or toggle any switch entity. Input Booleans Flip helper booleans to drive your automations. Assist Satellites Announce a message to an area through an assist satellite. ## Links / Resources [Section titled “Links / Resources”](#links--resources) Suggest a Feature / Report a Bug Thought of a feature that could be added? Found an issue? Suggest it here. [Open issues](https://github.com/timmo001/go-automate/issues) Contribute to the Application Contribute to the project by submitting a pull request. [View repository](https://github.com/timmo001/go-automate) Install from the AUR Arch users can install the latest development build from the AUR. [go-automate-git](https://aur.archlinux.org/packages/go-automate-git) # Overview > Guides and reference for installing, configuring, and using Go Automate. Go Automate runs on your machine and bridges your shortcuts and scripts to Home Assistant. Use these guides to get set up and start automating. ## Getting Started [Section titled “Getting Started”](#getting-started) [Install ](/install/)Install Go Automate from the AUR or build it from source. [Configuration ](/configuration/)Point Go Automate at your Home Assistant URL and token. [Running the Bridge ](/running/)Run the Home Assistant bridge as a systemd user service. ## Using [Section titled “Using”](#using) [CLI ](/using/cli/)Run tasks and control Home Assistant from the command line. [TUI ](/using/tui/)Browse and run commands from an interactive terminal menu. [Home Assistant ](/using/home-assistant/)Control lights, switches, input booleans and assist satellites. [Watching Entities ](/using/watching/)Stream entity state changes into scripts and status bars. [Notifications ](/using/notifications/)Send desktop notifications with notify-send. ## Reference [Section titled “Reference”](#reference) [Overview ](/reference/)How the command tree and the bridge fit together. [Commands ](/reference/commands/)Every command, alias and flag in one place. [Bridge Protocol ](/reference/bridge/)The Unix socket JSON protocol the bridge speaks. ## LLMs [Section titled “LLMs”](#llms) [LLMs ](/llms/)Feed the documentation to an agent using llms.txt. # Configuration > Point Go Automate at your Home Assistant URL and long-lived access token. Go Automate reads its configuration from a single YAML file. It needs your Home Assistant URL and a long-lived access token to connect. ## Config file location [Section titled “Config file location”](#config-file-location) The config file is `config.yml` inside the Go Automate config directory. The directory is resolved in this order: * `$XDG_CONFIG_HOME/go-automate` if `XDG_CONFIG_HOME` is set. * `~/.config/go-automate` otherwise. So on a typical Linux setup the file lives at `~/.config/go-automate/config.yml`. ## Config format [Section titled “Config format”](#config-format) \~/.config/go-automate/config.yml ```yaml homeassistant: url: http://homeassistant.local:8123 token: your-long-lived-access-token ``` * `homeassistant.url` — the base URL of your Home Assistant instance. Defaults to `http://homeassistant.local:8123`. Use `https://` for TLS; Go Automate connects over `ws://` or `wss://` automatically based on the scheme. * `homeassistant.token` — a Home Assistant long-lived access token. ## First-run setup [Section titled “First-run setup”](#first-run-setup) If the token is empty when you start Go Automate in an interactive terminal, it walks you through a short setup form and writes the file for you. 1. Run the app in a terminal: ```bash go-automate ``` 2. Enter your Home Assistant URL and long-lived access token when prompted. 3. Go Automate saves `config.yml` and continues. Caution In a non-interactive session (for example a systemd service) Go Automate cannot prompt you. If the token is missing it exits with an error telling you to configure the file or run it interactively once. Always run it interactively first, or write `config.yml` yourself, before enabling the [bridge service](/running/). ## Creating a long-lived access token [Section titled “Creating a long-lived access token”](#creating-a-long-lived-access-token) 1. In Home Assistant, open your profile (click your username in the sidebar). 2. Go to the **Security** tab and scroll to **Long-lived access tokens**. 3. Select **Create token**, give it a name such as `go-automate`, and copy the value. The token is shown only once, so paste it straight into your config or the setup form. ## Next steps [Section titled “Next steps”](#next-steps) * [Run the bridge](/running/) so watchers and status bars stay cheap on the network. * Start controlling [Home Assistant](/using/home-assistant/). # Install > Install Go Automate from the AUR or build it from source. Go Automate is a Linux-first command-line tool. You can install it from the AUR on Arch, or build it from source on any platform with a Go toolchain. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * [Go](https://go.dev/dl/) 1.23 or newer to build from source. * `notify-send` (from `libnotify`) for the [notify](/using/notifications/) command. * Optionally, a terminal emulator (`foot`, `alacritty`, `kitty`, `ghostty` or `xterm`) so the [TUI](/using/tui/) can open in its own window. * For building the Arch package locally: `base-devel` and an AUR helper such as `yay`. ## Install [Section titled “Install”](#install) * Arch Linux Install the latest development build from the AUR package [go-automate-git](https://aur.archlinux.org/packages/go-automate-git). It builds and installs from the latest `main` branch, which is updated on every commit. ```bash yay -S go-automate-git ``` Alternatively, build a local package from a checkout and install it: ```bash make create_arch yay -U dist/go-automate--1-x86_64.pkg.tar.zst ``` * Build from source 1. Clone the [repository](https://github.com/timmo001/go-automate): ```bash git clone https://github.com/timmo001/go-automate.git cd go-automate ``` 2. Build the binary: ```bash go build ``` Or use the Makefile to build the app and the [TUI](/using/tui/) together: ```bash make build_all ``` 3. Move the binary somewhere on your `PATH`, for example: ```bash install -Dm755 go-automate ~/.local/bin/go-automate ``` ## What the Arch package installs [Section titled “What the Arch package installs”](#what-the-arch-package-installs) The Arch package installs: * `/usr/bin/go-automate` — the main binary. * `/usr/lib/systemd/user/go-automate-home-assistant-bridge.service` — the [bridge](/running/) user service. The post-install script enables the bridge service globally for future logins and tries to start it for the installing user when they have an active systemd user session. See [Running the Bridge](/running/) to finish setup. ## Next steps [Section titled “Next steps”](#next-steps) * [Configure](/configuration/) your Home Assistant URL and token. * [Run the bridge](/running/) as a user service. * Explore the [CLI](/using/cli/) and the [TUI](/using/tui/). # LLMs > Feed the Go Automate documentation to an agent using llms.txt. The Go Automate documentation is published in formats an agent can read directly, following the [llms.txt](https://llmstxt.org) convention. Point an agent at one of these files to give it the docs as context. ## Available files [Section titled “Available files”](#available-files) * [`/llms.txt`](https://go-automate.timmo.dev/llms.txt) - an index of the documentation with links to each section. Use this when you want the agent to pick what it needs. * [`/llms-full.txt`](https://go-automate.timmo.dev/llms-full.txt) - the entire documentation in a single file. Use this for the most complete context. * [`/llms-small.txt`](https://go-automate.timmo.dev/llms-small.txt) - a trimmed version for smaller context windows. These files are generated from the docs at build time, so they stay in sync with the rest of the site. ## How to use them [Section titled “How to use them”](#how-to-use-them) * Paste one of the URLs above into an agent and ask it to read the page. * Use the actions in the page header on any docs page to copy the page as Markdown, then paste it straight into an agent. This gives the agent the content directly, so it does not need to fetch the page over the web. # Reference > How the Go Automate command tree and the Home Assistant bridge fit together. Go Automate is a command-line tool built on [urfave/cli](https://cli.urfave.org). It talks to Home Assistant over the WebSocket API and runs a local bridge that shares a single connection with every watcher on your machine. ## Sections [Section titled “Sections”](#sections) * [Commands](/reference/commands/): every command, alias and flag. * [Bridge Protocol](/reference/bridge/): the Unix socket JSON protocol the bridge speaks. [Commands ](/reference/commands/)The full command tree with flags and aliases. [Bridge Protocol ](/reference/bridge/)The socket actions and responses behind the bridge. ## How it connects [Section titled “How it connects”](#how-it-connects) When you run a command that needs Home Assistant, Go Automate: 1. Loads your [configuration](/configuration/) (URL and token). 2. Opens a WebSocket to `/:///api/websocket` and authenticates with the token. 3. Sends the request (a service call, a state read, or an event subscription). The [bridge](/running/) does the same upstream connection once and keeps it open, then serves cached state and live updates to local clients over a Unix socket. This keeps many watchers cheap: they connect to the socket instead of each opening their own WebSocket to Home Assistant. # Bar JSON > The machine-readable JSON output that entity watchers emit for status bars and shell modules. `--bar-json` switches an entity watcher from plain text to machine-readable JSON. Each state change prints one JSON object on its own line. It is a generic JSON-lines contract, so it works with any status bar, shell or script that reads line-delimited JSON, including [Waybar](https://github.com/Alexays/Waybar) and [Quickshell](https://quickshell.org/). It is supported by both watch commands: * [`ha bridge watch entity`](/reference/commands/) (recommended) * [`ha watch entity`](/reference/commands/) See [Watching Entities](/using/watching/) for when to use each one. ## Output shape [Section titled “Output shape”](#output-shape) Every line is a JSON object with exactly three string fields, always present: ```json { "text": "Guest", "tooltip": "Guest mode is on", "class": "active" } ``` | Field | Purpose | | --------- | ------------------------- | | `text` | The label to render. | | `tooltip` | The hover tooltip. | | `class` | A class name for styling. | The field names match Waybar’s custom-module schema (`"return-type": "json"`), but the object is plain JSON. Any consumer can read the line and use whichever fields it supports, so the same command drives a Waybar module, a Quickshell widget or a custom script. ## How the fields are derived [Section titled “How the fields are derived”](#how-the-fields-are-derived) A watcher treats the entity state as either `on` or not. The check is a literal comparison against the string `on`, so any other value (`off`, `unavailable`, a sensor reading, and so on) is handled by the “not on” branch. All three fields default to the raw entity state. The output flags then refine them: **When the state is `on`:** * `text` becomes `--icon` if set, then `--text-on` is appended (space-joined). * `tooltip` becomes `--tooltip-on` if set. * `class` becomes `--class-on` if set. **When the state is not `on`:** * `text` becomes empty if `--hide-off` is set, otherwise `--icon` if set, otherwise the raw state. `--text-off` is then appended. * `tooltip` becomes `--tooltip-off` if set. * `class` becomes `--class-off` if set. * With `--hide-off`, `hidden` is appended to `class` (so the bar can hide the module while keeping the line valid JSON). Any flag you leave unset keeps the field at its default, so a minimal `--bar-json` run still produces valid output built from the raw state. ## Flags [Section titled “Flags”](#flags) These flags apply in `--bar-json` mode on both watch commands: | Flag | Effect | | --------------- | ---------------------------------------------------------------------------------------- | | `--bar-json` | Emit JSON lines (`text`, `tooltip`, `class`) for status bars. | | `--icon` | Text or icon to show for the state. Replaces the raw state text. | | `--text-on` | Text appended when the state is `on`. | | `--text-off` | Text appended when the state is not `on`. | | `--tooltip-on` | Tooltip when the state is `on`. | | `--tooltip-off` | Tooltip when the state is not `on`. | | `--class-on` | Status-bar class when the state is `on`. | | `--class-off` | Status-bar class when the state is not `on`. | | `--hide-off` | Hide the module (empty `text`, `hidden` appended to `class`) when the state is not `on`. | Connection flags differ by command. See [Commands](/reference/commands/) for `--socket`, `--direct` and `--bridge-socket`. ## Example [Section titled “Example”](#example) ```bash go-automate ha bridge watch entity input_boolean.guest_mode \ --bar-json \ --text-on "Guest" \ --tooltip-on "Guest mode is on" \ --tooltip-off "Guest mode is off" \ --class-on "active" \ --hide-off ``` With the entity on, this prints: ```json { "text": "Guest", "tooltip": "Guest mode is on", "class": "active" } ``` With the entity off, `--hide-off` blanks the text and marks the class hidden: ```json { "text": "", "tooltip": "Guest mode is off", "class": "off hidden" } ``` ## Consuming the output [Section titled “Consuming the output”](#consuming-the-output) Any program that reads line-delimited JSON from a process can consume a watcher. The watcher streams a JSON line on every state change, so the consumer updates live. ### Waybar [Section titled “Waybar”](#waybar) \~/.config/waybar/config.jsonc ```json "custom/guest_mode": { "exec": "go-automate ha bridge watch entity input_boolean.guest_mode --bar-json --text-on 'Guest' --tooltip-on 'Guest mode on' --tooltip-off 'Guest mode off' --class-on 'active' --hide-off", "return-type": "json", "restart-interval": 5 } ``` The `restart-interval` makes Waybar restart the watcher if it ever exits (for example while the bridge restarts). ### Other shells and scripts [Section titled “Other shells and scripts”](#other-shells-and-scripts) Quickshell and similar shells run the same command and parse each line from the process’s standard output. The contract is identical: read a line, decode the JSON, use the `text`, `tooltip` and `class` fields. From a shell, you can read it line by line: ```bash go-automate ha bridge watch entity input_boolean.guest_mode --bar-json | while IFS= read -r line; do printf '%s\n' "$line" | jq -r '.text' done ``` Restart the watcher if it exits, the same way Waybar’s `restart-interval` does, so the consumer reconnects after a bridge restart. ## Next steps [Section titled “Next steps”](#next-steps) * See [Watching Entities](/using/watching/) for choosing between the bridge and direct watchers. * Run the [bridge](/running/) so many bar modules share one connection to Home Assistant. # Bridge Protocol > The Unix socket JSON protocol the Go Automate Home Assistant bridge speaks. The [bridge](/running/) keeps one WebSocket connection to Home Assistant and serves cached state and live updates to local clients over a Unix domain socket. Most of the time you use it through [`ha bridge watch entity`](/using/watching/), but the protocol is simple enough to speak directly from your own scripts. ## Socket location [Section titled “Socket location”](#socket-location) By default the bridge listens at: ```text $XDG_RUNTIME_DIR/go-automate/home-assistant.sock ``` If `XDG_RUNTIME_DIR` is not set, it falls back to the system temp directory. The socket directory is created with `0700` permissions and the socket with `0600`, so only your user can connect. Override the path with `--socket` on [`ha bridge serve`](/reference/commands/#ha-bridge-serve). ## Transport [Section titled “Transport”](#transport) The protocol is newline-delimited JSON over the socket. The client sends a single request object, and the bridge replies with one or more response objects on the same connection. ## Request format [Section titled “Request format”](#request-format) Request ```json { "action": "watch_entity", "entity_id": "light.bedroom_lamp" } ``` * `action`: the action to perform, either `get_entity` or `watch_entity`. * `entity_id`: the full entity ID, including its domain. Required for both actions. ## Response format [Section titled “Response format”](#response-format) Response ```json { "type": "snapshot", "entity_id": "light.bedroom_lamp", "state": { "entity_id": "light.bedroom_lamp", "state": "on" } } ``` * `type`: the response type — `snapshot`, `state_changed`, or `error`. * `entity_id`: the entity the response relates to. * `state`: an object with `entity_id` and the `state` string, or `null` if the bridge has no cached state for that entity. * `error`: a human-readable message, present only when `type` is `error`. ## Actions [Section titled “Actions”](#actions) ### `get_entity` [Section titled “get\_entity”](#get_entity) Returns a single `snapshot` response with the entity’s current cached state, then closes the connection. `state` is `null` if the entity is unknown to the bridge. ```bash SOCKET="$XDG_RUNTIME_DIR/go-automate/home-assistant.sock" echo '{"action":"get_entity","entity_id":"light.bedroom_lamp"}' | socat - "UNIX-CONNECT:$SOCKET" ``` ### `watch_entity` [Section titled “watch\_entity”](#watch_entity) Sends a `snapshot` immediately if the entity is known, then a `state_changed` response every time the entity changes. The connection stays open until the client disconnects or the bridge shuts down. ```bash SOCKET="$XDG_RUNTIME_DIR/go-automate/home-assistant.sock" echo '{"action":"watch_entity","entity_id":"light.bedroom_lamp"}' | socat - "UNIX-CONNECT:$SOCKET" ``` A change then arrives as: state\_changed ```json { "type": "state_changed", "entity_id": "light.bedroom_lamp", "state": { "entity_id": "light.bedroom_lamp", "state": "off" } } ``` ## Errors [Section titled “Errors”](#errors) A bad request returns an `error` response: Error response ```json { "type": "error", "error": "entity_id is required" } ``` Errors are returned when: * `entity_id` is missing. * `action` is not `get_entity` or `watch_entity`. * The request cannot be decoded as JSON. ## Upstream behaviour [Section titled “Upstream behaviour”](#upstream-behaviour) The bridge dials Home Assistant, authenticates with your token, reads all states once to build its cache, then subscribes to `state_changed` events. If the connection drops it reconnects every five seconds and re-broadcasts a fresh snapshot to active watchers, so clients recover automatically. # Commands > Every Go Automate command, alias and flag in one place. This page lists the full Go Automate command tree. Run any command with `--help` to see its usage at the terminal. ## `go-automate` [Section titled “go-automate”](#go-automate) The root command. With no subcommand in an interactive terminal, it launches the [TUI](/using/tui/) when the `go-automate-tui` binary is available; otherwise it shows CLI help. | Flag | Effect | | ----------- | --------------------------- | | `--version` | Print the version and exit. | | `--help` | Show help for the command. | ## `home-assistant` (alias `ha`) [Section titled “home-assistant (alias ha)”](#home-assistant-alias-ha) Interact with Home Assistant. ### `ha watch entity ` (alias `ha w e`) [Section titled “ha watch entity \ (alias ha w e)”](#ha-watch-entity-entity_id-alias-ha-w-e) Watch an entity for state changes. Uses the [bridge](/running/) by default and falls back to a direct WebSocket connection if the bridge is unavailable. Prefer `ha bridge watch entity` (below) for anything long-running. | Flag | Effect | | ----------------- | -------------------------------------------------------------- | | `--bar-json` | Emit JSON lines (`text`, `tooltip`, `class`) for status bars. | | `--icon` | Text/icon to show for the state in bar JSON mode. | | `--text-on` | Text appended when the state is `on`. | | `--text-off` | Text appended when the state is not `on`. | | `--tooltip-on` | Tooltip when the state is `on`. | | `--tooltip-off` | Tooltip when the state is not `on`. | | `--class-on` | Status-bar class when the state is `on`. | | `--class-off` | Status-bar class when the state is not `on`. | | `--hide-off` | Hide the module when the state is not `on`. | | `--direct` | Bypass the bridge and connect directly (higher network usage). | | `--bridge-socket` | Path to the bridge socket to try before falling back. | See [Bar JSON](/reference/bar-json/) for the output shape and how the `--bar-json` flags combine. ### `ha bridge serve` [Section titled “ha bridge serve”](#ha-bridge-serve) Serve the shared Home Assistant bridge. See [Running the Bridge](/running/). | Flag | Effect | | ---------- | ------------------------------------------------------------------------------------------ | | `--socket` | Path to the bridge socket. Defaults to `$XDG_RUNTIME_DIR/go-automate/home-assistant.sock`. | ### `ha bridge watch entity ` (alias `ha b w e`) [Section titled “ha bridge watch entity \ (alias ha b w e)”](#ha-bridge-watch-entity-entity_id-alias-ha-b-w-e) Watch an entity through the bridge (recommended). Takes the same `--bar-json` output flags as `ha watch entity`. See [Bar JSON](/reference/bar-json/) for the output shape. | Flag | Effect | | -------------------------------- | ------------------------------------------------- | | `--bar-json` | Emit JSON lines for status bars. | | `--icon` | Text/icon to show for the state in bar JSON mode. | | `--text-on` / `--text-off` | Text appended for the on / not-on states. | | `--tooltip-on` / `--tooltip-off` | Tooltip for the on / not-on states. | | `--class-on` / `--class-off` | Status-bar class for the on / not-on states. | | `--hide-off` | Hide the module when the state is not `on`. | | `--socket` | Path to the bridge socket. | ### `ha assist_satellite announce ` (alias `ha as a`) [Section titled “ha assist\_satellite announce \ \ (alias ha as a)”](#ha-assist_satellite-announce-area_id-message-alias-ha-as-a) Announce a message to an area through an assist satellite. The first argument is the area ID; the second is the message. ```bash go-automate ha assist_satellite announce living_room "Dinner is ready" ``` ### `ha light` (alias `ha l`) [Section titled “ha light (alias ha l)”](#ha-light-alias-ha-l) Control light entities. Each subcommand takes the entity name without its domain. | Subcommand | Alias | Service | | ----------------- | ----- | ---------------- | | `turn-on ` | `on` | `light.turn_on` | | `turn-off ` | `off` | `light.turn_off` | | `toggle ` | `t` | `light.toggle` | ### `ha switch` (alias `ha s`) [Section titled “ha switch (alias ha s)”](#ha-switch-alias-ha-s) Control switch entities. Same subcommands as `light`. | Subcommand | Alias | Service | | ----------------- | ----- | ----------------- | | `turn-on ` | `on` | `switch.turn_on` | | `turn-off ` | `off` | `switch.turn_off` | | `toggle ` | `t` | `switch.toggle` | ### `ha input_boolean` (alias `ha ib`) [Section titled “ha input\_boolean (alias ha ib)”](#ha-input_boolean-alias-ha-ib) Control input boolean helpers. Same subcommands as `light`. | Subcommand | Alias | Service | | ----------------- | ----- | ------------------------ | | `turn-on ` | `on` | `input_boolean.turn_on` | | `turn-off ` | `off` | `input_boolean.turn_off` | | `toggle ` | `t` | `input_boolean.toggle` | ## `notify

[body]` (alias `n`) [Section titled “notify \

\[body\] (alias n)”](#notify-summary-body-alias-n) Send a desktop notification through `notify-send`. The first argument is the summary; the optional second argument is the body. See [Notifications](/using/notifications/). ```bash go-automate notify "Build complete" "Your build finished successfully" ``` ## `tui` [Section titled “tui”](#tui) Launch the interactive [TUI](/using/tui/) menu. # Running the Bridge > Run the Go Automate Home Assistant bridge as a systemd user service. The bridge keeps a single WebSocket connection to Home Assistant and shares it with every watcher on your machine. Running it as a background service means commands like [`ha bridge watch entity`](/using/watching/) and status-bar modules reuse one connection instead of each opening their own. ## How it works [Section titled “How it works”](#how-it-works) The bridge listens on a Unix socket, by default at `$XDG_RUNTIME_DIR/go-automate/home-assistant.sock`. Watchers connect to that socket rather than to Home Assistant directly. The service runs: ```bash go-automate ha bridge serve ``` See the [Bridge Protocol](/reference/bridge/) reference for the socket details. ## Systemd user service [Section titled “Systemd user service”](#systemd-user-service) The Arch package installs a user service called `go-automate-home-assistant-bridge.service` and enables it globally for future logins. If it is not running in your current session yet, enable it manually. 1. Reload the user systemd daemon: ```bash systemctl --user daemon-reload ``` 2. Enable and start the service: ```bash systemctl --user enable --now go-automate-home-assistant-bridge.service ``` 3. Check the service status: ```bash systemctl --user status go-automate-home-assistant-bridge.service ``` To follow the logs: ```bash journalctl --user -u go-automate-home-assistant-bridge.service -f ``` ## Installing the service manually [Section titled “Installing the service manually”](#installing-the-service-manually) If you built from source, install the unit yourself: 1. Copy the unit file from the repository to your user units directory: ```bash mkdir -p ~/.config/systemd/user cp .scripts/linux/go-automate-home-assistant-bridge.service ~/.config/systemd/user/ ``` 2. Reload, enable and start it: ```bash systemctl --user daemon-reload systemctl --user enable --now go-automate-home-assistant-bridge.service ``` ## Running it in the foreground [Section titled “Running it in the foreground”](#running-it-in-the-foreground) For quick troubleshooting you can run the bridge directly instead of as a service: ```bash go-automate ha bridge serve ``` Pass `--socket` to use a custom socket path: ```bash go-automate ha bridge serve --socket /tmp/go-automate-ha.sock ``` ## Next steps [Section titled “Next steps”](#next-steps) * [Watch entities](/using/watching/) through the bridge. * Wire watchers into a [status bar](/using/watching/#status-bars). # CLI > Run tasks and control Home Assistant from the Go Automate command line. The Go Automate CLI groups its commands by area. Most live under the `home-assistant` command (aliased `ha`), with `notify` and `tui` available at the top level. Every command group has short aliases so you can bind them to keyboard shortcuts comfortably. ## Command groups [Section titled “Command groups”](#command-groups) | Command | Alias | Purpose | | ---------------- | ----- | ------------------------------------------ | | `home-assistant` | `ha` | Control Home Assistant and watch entities. | | `notify` | `n` | Send a desktop notification. | | `tui` | | Launch the interactive terminal menu. | For the full command tree with every flag, see the [Commands reference](/reference/commands/). ## Home Assistant [Section titled “Home Assistant”](#home-assistant) The `ha` command controls entities and watches their state: ```bash # Toggle a light entity (light.bedroom_lamp) go-automate ha light toggle bedroom_lamp # Turn a switch on go-automate ha switch turn-on desk_fan # Announce to an area through an assist satellite go-automate ha assist_satellite announce living_room "Dinner is ready" ``` See [Home Assistant](/using/home-assistant/) for the full set of control commands, and [Watching Entities](/using/watching/) for live state. ## Notify [Section titled “Notify”](#notify) Send a desktop notification through `notify-send`: ```bash go-automate notify "Build complete" "Your build finished successfully" ``` See [Notifications](/using/notifications/) for the details. ## The TUI [Section titled “The TUI”](#the-tui) Running Go Automate with no command in an interactive terminal launches the [TUI](/using/tui/) automatically when the `go-automate-tui` binary is available. You can also launch it explicitly: ```bash go-automate tui ``` If you are not in an interactive terminal, or the TUI binary is not found, Go Automate continues in CLI mode. ## Tips [Section titled “Tips”](#tips) * Use the short aliases for shortcuts, for example `go-automate ha l toggle bedroom_lamp`. * Entity commands take the entity name **without** its domain prefix. `go-automate ha light turn-on bedroom_lamp` acts on `light.bedroom_lamp`. * Wrap multi-word arguments in quotes, for example announce messages. ## Next steps [Section titled “Next steps”](#next-steps) * Control [Home Assistant](/using/home-assistant/). * [Watch entities](/using/watching/) and feed [status bars](/using/watching/#status-bars). * Browse everything in the [Commands reference](/reference/commands/). # Home Assistant > Control lights, switches, input booleans and assist satellites from the command line. The `home-assistant` command (aliased `ha`) calls Home Assistant services over the WebSocket API. It connects using the URL and token from your [configuration](/configuration/), calls the service, and exits. ## Entity naming [Section titled “Entity naming”](#entity-naming) Control commands take the entity name **without** its domain prefix. The domain comes from the command you run, so: ```bash go-automate ha light turn-on bedroom_lamp ``` acts on the entity `light.bedroom_lamp`. ## Lights [Section titled “Lights”](#lights) Turn a light on, off, or toggle it: ```bash go-automate ha light turn-on bedroom_lamp go-automate ha light turn-off bedroom_lamp go-automate ha light toggle bedroom_lamp ``` Aliases keep it short for keyboard shortcuts — `ha l on`, `ha l off`, and `ha l t`: ```bash go-automate ha l t bedroom_lamp ``` ## Switches [Section titled “Switches”](#switches) Switches work the same way under the `switch` command (alias `s`): ```bash go-automate ha switch turn-on desk_fan go-automate ha switch toggle desk_fan ``` ## Input booleans [Section titled “Input booleans”](#input-booleans) Flip helper booleans that drive your automations with the `input_boolean` command (alias `ib`): ```bash go-automate ha input_boolean turn-on guest_mode go-automate ha input_boolean toggle guest_mode ``` ## Assist satellites [Section titled “Assist satellites”](#assist-satellites) Announce a message to an area through an assist satellite with `assist_satellite announce` (alias `as a`). Pass the area ID first, then the message: ```bash go-automate ha assist_satellite announce living_room "Dinner is ready" ``` ## Service actions at a glance [Section titled “Service actions at a glance”](#service-actions-at-a-glance) | Command | Alias | Service | Target | | -------------------------------------------------- | ------------------------ | ----------------------------------------------- | ---------------------- | | `ha light turn-on` / `turn-off` / `toggle` | `ha l on` / `off` / `t` | `light.turn_on` / `turn_off` / `toggle` | `light.` | | `ha switch turn-on` / `turn-off` / `toggle` | `ha s on` / `off` / `t` | `switch.turn_on` / `turn_off` / `toggle` | `switch.` | | `ha input_boolean turn-on` / `turn-off` / `toggle` | `ha ib on` / `off` / `t` | `input_boolean.turn_on` / `turn_off` / `toggle` | `input_boolean.` | | `ha assist_satellite announce` | `ha as a` | `assist_satellite.announce` | `area_id` | ## Next steps [Section titled “Next steps”](#next-steps) * [Watch entities](/using/watching/) to react to state changes. * See every flag in the [Commands reference](/reference/commands/). # Notifications > Send desktop notifications from Go Automate with notify-send. The `notify` command (aliased `n`) sends a desktop notification. It shells out to `notify-send`, so it works with any notification daemon that implements the freedesktop notification spec (for example [mako](https://github.com/emersion/mako) or [dunst](https://github.com/dunst-project/dunst)). ## Requirements [Section titled “Requirements”](#requirements) * `notify-send`, provided by `libnotify`. * A running notification daemon. ## Usage [Section titled “Usage”](#usage) Pass a summary and, optionally, a body: ```bash go-automate notify "Build complete" "Your build finished successfully" ``` The first argument is the summary (title) and the second is the body. Use the `n` alias for shortcuts: ```bash go-automate n "Backup finished" ``` Wrap multi-word arguments in quotes so they are passed as a single value. ## Using it in automations [Section titled “Using it in automations”](#using-it-in-automations) Because it is a single command, `notify` slots into scripts, build steps and keyboard shortcuts: ```bash make build && go-automate notify "Build complete" || go-automate notify "Build failed" ``` ## Next steps [Section titled “Next steps”](#next-steps) * Control [Home Assistant](/using/home-assistant/) from the same shortcuts. * Browse every command in the [Commands reference](/reference/commands/). # TUI > Browse and run Go Automate commands from an interactive terminal menu. The TUI is an interactive terminal menu for Go Automate. It is a separate binary, `go-automate-tui`, that shells out to the main `go-automate` CLI, so anything you can do in the menu maps to a command you could run yourself. ## Launching [Section titled “Launching”](#launching) There are three ways to open the TUI: * **Automatically** — run `go-automate` with no command in an interactive terminal. When the `go-automate-tui` binary is found, the menu opens. * **Explicitly** — run the launcher command: ```bash go-automate tui ``` * **Directly** — run the TUI binary itself: ```bash go-automate-tui ``` Go Automate looks for the TUI binary next to the running `go-automate` executable first, then on your `PATH`. If it cannot be found, the CLI continues normally. ## The menu [Section titled “The menu”](#the-menu) The main menu covers the most common tasks: * **Bridge Serve** — start the [Home Assistant bridge](/running/) in the foreground. * **Home Assistant** — open a submenu for lights, switches, input booleans and assist satellites. * **Watch Entity** — watch an entity’s state through the bridge. * **Notify** — send a desktop notification. * **Quit** — leave the menu. Selecting a control action opens a small popup to collect its arguments, such as the entity name to toggle or the message to announce, then runs the matching command. ## Search [Section titled “Search”](#search) Start typing to fuzzy-search the menu. Items also match helpful keywords, so typing `lamp`, `monitor` or `announce` jumps to the right action. Vim-style shortcuts work too: `:w` for watch, `:n` for notify, and `:q` to quit. ## Building the TUI [Section titled “Building the TUI”](#building-the-tui) The TUI is built with [Bun](https://bun.sh) and [OpenTUI](https://github.com/sst/opentui). Build it alongside the main binary: ```bash make build_all ``` Or build just the TUI from the `tui/` directory: ```bash cd tui bun install bun run build ``` During development you can run it with live reload: ```bash cd tui bun run dev ``` ## Next steps [Section titled “Next steps”](#next-steps) * Prefer the command line? See the [CLI](/using/cli/). * Set up the [bridge](/running/) so Watch Entity stays cheap on the network. # Watching Entities > Stream Home Assistant entity state changes into scripts and status bars. Go Automate can watch a Home Assistant entity and print its state every time it changes. This powers shell scripts and status-bar modules that react to your home in real time. ## Two ways to watch [Section titled “Two ways to watch”](#two-ways-to-watch) * **Through the bridge (recommended)** — `ha bridge watch entity` connects to the shared [bridge](/running/), so many watchers reuse one connection to Home Assistant. This is the best choice for status bars and long-running watchers. * **Direct (troubleshooting only)** — `ha watch entity` opens its own WebSocket connection. It uses the bridge by default and only falls back to a direct connection if the bridge is unavailable. Force a direct connection with `--direct` when debugging. Caution Direct connections open a new WebSocket per watcher and increase network usage. Prefer the bridge for anything that runs continuously. Start it with [`go-automate ha bridge serve`](/running/). ## Watch through the bridge [Section titled “Watch through the bridge”](#watch-through-the-bridge) ```bash go-automate ha bridge watch entity input_boolean.guest_mode ``` The watcher prints the current state immediately, then prints again on every change. Pass `--socket` to use a non-default bridge socket path: ```bash go-automate ha bridge watch entity input_boolean.guest_mode --socket /tmp/go-automate-ha.sock ``` ## Watch directly [Section titled “Watch directly”](#watch-directly) `ha watch entity` uses the bridge when it can and falls back to a direct connection otherwise: ```bash go-automate ha watch entity sensor.living_room_temperature ``` Force a direct connection for troubleshooting with `--direct`: ```bash go-automate ha watch entity sensor.living_room_temperature --direct ``` ## Status bars [Section titled “Status bars”](#status-bars) Add `--bar-json` to emit machine-readable JSON lines instead of plain text. Each line is an object with `text`, `tooltip` and `class` that any status bar, shell or script can consume, including [Waybar](https://github.com/Alexays/Waybar) and [Quickshell](https://quickshell.org/). See [Bar JSON](/reference/bar-json/) for the full output contract and every flag. ```bash go-automate ha bridge watch entity input_boolean.guest_mode \ --bar-json \ --text-on "Guest" \ --tooltip-on "Guest mode is on" \ --tooltip-off "Guest mode is off" \ --class-on "active" \ --hide-off ``` For the full output contract, every `--bar-json` flag and a complete Waybar module, see [Bar JSON](/reference/bar-json/). Connection flags differ by command: | Flag | Command | Effect | | ----------------- | ------------------------ | ----------------------------------------------------- | | `--socket` | `ha bridge watch entity` | Path to the bridge socket. | | `--direct` | `ha watch entity` | Bypass the bridge and connect directly. | | `--bridge-socket` | `ha watch entity` | Path to the bridge socket to try before falling back. | ## Next steps [Section titled “Next steps”](#next-steps) * See [Bar JSON](/reference/bar-json/) to wire a watcher into a status bar. * Make sure the [bridge](/running/) is running for the lowest network usage. * See the [Bridge Protocol](/reference/bridge/) for how watchers talk to the bridge.