Home Assistant Command-line Interface

To interact with your Home Assistant instance, you must provide a server URL and a Long-Lived Access Token.

1. Generate a Token: Go to your Home Assistant profile page (e.g., http://homeassistant.local:8123/profile), scroll to "Long-Lived Access Tokens", and generate one.
2. Set Credentials: You can pass --server and --token as parameters to every command, but it is recommended to set them as environment variables:

$ export HASS_SERVER=http://homeassistant.local:8123
$ export HASS_TOKEN=<your_secret_token>

$ export HASS_SERVER=http://homeassistant.local:8123
$ export HASS_TOKEN=<secret>

For users of the Home Assistant Operating System, certain commands (like ha commands) require access to the Supervisor API.

1. Install and start the Remote API proxy add-on.
2. Retrieve your Supervisor API key from the add-on logs.
3. Set the HASS_SUPERVISOR_TOKEN environment variable:

$ export HASS_SUPERVISOR_TOKEN=<supervisor_secret>

Use the service command to interact with Home Assistant services.

List Services

You can list services and filter them using regular expressions.

# List services matching a pattern
$ hass-cli service list 'home.*toggle'

# Get detailed service information in YAML format
$ hass-cli -o yaml service list homeassistant.toggle

Call a Service

To trigger a service (e.g., creating a backup), use service call:

# Example: Create a backup
$ hass-cli service call backup.create

You can enable shell autocompletion for hass-cli commands using the following commands depending on your shell:

• Bash: source <(_HASS_CLI_COMPLETE=bash_source hass-cli)
• Zsh: source <(_HASS_CLI_COMPLETE=zsh_source hass-cli)
• Fish: eval (_HASS_CLI_COMPLETE=fish_source hass-cli)

$ source <(_HASS_CLI_COMPLETE=bash_source hass-cli) # for bash
$ source <(_HASS_CLI_COMPLETE=zsh_source hass-cli)  # for zsh
$ eval (_HASS_CLI_COMPLETE=fish_source hass-cli)    # for fish

To develop on hass-cli, it is recommended to use a Python virtual environment to ensure isolation. Follow these steps:

1. Clone the repository.
2. Create and activate a virtual environment.
3. Run the provided setup script.
4. Install the package in editable mode.

After setup, you can run hass-cli directly from your terminal to test changes.

# Create and activate virtual environment
python3 -m venv .
source bin/activate

# Run setup script
script/setup

# Install in editable mode
pip3 install --editable .

# Run the CLI
$ hass-cli

To enable tab-completion for commands and entity attributes (like light.<TAB>), add the following to your shell configuration file. This method is recommended as it uses eval to avoid triggering a full hass-cli run every time a shell starts.

Zsh

Add this to your .zshrc:

eval "$(_HASS_CLI_COMPLETE=source_zsh hass-cli)"

Bash

Add this to your .bashrc:

eval "$(_HASS_CLI_COMPLETE=source hass-cli)"

Note: If your Home Assistant instance is secured or remote, you must set the HASS_SERVER and HASS_TOKEN environment variables for autocompletion to fetch entity lists.

# Required for remote/secured instances to enable entity autocompletion
export HASS_SERVER=http://homeassistant.local:8123
export HASS_TOKEN=your_bearer_token_here

The hass-cli uses a plugin-based architecture. Instead of a static list of commands, it dynamically discovers and loads commands from a plugins directory.

When you run a command, the HomeAssistantCli class (which inherits from click.MultiCommand) performs the following:

1. Discovery: It scans the plugins folder for .py files (excluding those starting with __).
2. Loading: It imports the module and looks for a cli object within that module.
3. Execution: It invokes the imported cli object as the command group or command.

This allows the CLI to be easily extended with new functionality by adding new plugin files.

The CLI can automatically locate a Home Assistant instance on the local network using mDNS (Zeroconf).

When server is set to auto:

1. If HASSIO_TOKEN is in the environment but HASS_TOKEN is not, it uses const.DEFAULT_SERVER_MDNS.
2. Otherwise, it attempts to locate the instance via Zeroconf by looking for _home-assistant._tcp.local. services.
3. If multiple instances are found, resolution fails and the user should use the --server flag to specify one explicitly.
4. If no instance is found and no explicit server is provided, the CLI exits with code 3.

Control how hass-cli displays data using the following flags:

• --output=yaml or -o yaml: Output data in YAML format.
• --output=json or -o json: Output data in JSON format.
• --no-headers: Suppress the table header in output.
• --table-format <format>: Select a table format. Supported formats (via tabulate) include: plain, simple, github, grid, fancy_grid, pipe, orgtbl, rst, mediawiki, html, latex, latex_raw, latex_booktabs, or tsv. Default is simple.
• --columns=<NAME>=<JSONPATH>,...: Control which columns are shown. For entities, the default is: --columns=ENTITY=entity_id,DESCRIPTION=attributes.friendly_name,STATE=state,CHANGED=last_changed.
• --sort-by <attribute>: Sort the output by a specific attribute found in the underlying JSON/YAML data.