### Scripting with hass-cli Bash Example

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Demonstrates how to fetch state data, extract specific fields using jq, and call a service to control a light. Ensure jq is installed for JSON processing.

```bash
#!/bin/bash

# Get JSON data for processing
data=$(hass-cli -o json state list)

# Extract specific fields
entity=$(echo "$data" | jq -r '.[0].entity_id')

# Process results
hass-cli service call light.turn_on --arguments entity_id="$entity"
```

--------------------------------

### Install Home Assistant CLI

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use pip to install the homeassistant-cli package.

```bash
pip install homeassistant-cli
```

--------------------------------

### Get Home Assistant System Info

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_info()` to fetch general information about your Home Assistant system, such as version and installation details.

```python
get_info()            # Get system info
```

--------------------------------

### List Services with Regex Filter

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

List available services, optionally filtering them using a regular expression. This example lists services starting with 'home'.

```bash
$ hass-cli service list 'home.*toggle'
```

--------------------------------

### YAML List Examples

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/07-yaml-utilities.md

Shows how to define lists in YAML using both inline and block styles.

```yaml
# Inline style
lights: [light.kitchen, light.bedroom, light.bathroom]

# Block style
lights:
  - light.kitchen
  - light.bedroom
  - light.bathroom
```

--------------------------------

### Get Home Assistant Configuration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_config()` to retrieve the current configuration settings of your Home Assistant instance. This provides insights into your setup.

```python
get_config()          # Get configuration
```

--------------------------------

### Install Home Assistant CLI with Pip

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Install the Home Assistant CLI in editable mode using pip. This is useful for development purposes.

```bash
pip3 install --editable .
```

--------------------------------

### Get Detailed Service Information in YAML

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Retrieve detailed information about a specific service, including its description, fields, and examples, using YAML output format.

```bash
$ hass-cli -o yaml service list homeassistant.toggle
```

--------------------------------

### Setup Docker Wrapper Script

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Download and make executable a script to use hass-cli from Docker, enabling auto-completion and environment variable access.

```bash
$ curl https://raw.githubusercontent.com/home-assistant/home-assistant-cli/master/docker-hass-cli > hass-cli
$ chmod +x hass-cli
```

--------------------------------

### Plugin Structure Example

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/08-project-structure.md

Demonstrates the structure of a typical plugin module, including necessary imports and the definition of Click commands using `@click.group` and `@cli.command`.

```python
# homeassistant_cli/plugins/state.py

import click
from homeassistant_cli.cli import pass_context
from homeassistant_cli.config import Configuration

@click.group("state")
@pass_context
def cli(ctx: Configuration) -> None:
    """Get info on entity state from Home Assistant."""

@cli.command()
@click.argument("entity")
@pass_context
def get(ctx: Configuration, entity: str) -> None:
    """Get/read entity state from Home Assistant."""
    # Implementation
```

--------------------------------

### Install with Nix Environment

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Install hass-cli on NixOS. The latest release might only be available in the 'unstable' channel.

```bash
$ nix-env -iA nixos.home-assistant-cli
```

--------------------------------

### Get System Info

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Retrieves system and Home Assistant version information. Use the -o flag to specify output format.

```bash
hass-cli system info
```

```bash
hass-cli -o yaml system info
```

--------------------------------

### List Integrations

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_config_entries()` to list all configured integrations (config entries) in Home Assistant. This provides an overview of installed components.

```python
get_config_entries()          # List integrations
```

--------------------------------

### Get All Config Entries

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieve a list of all configuration entries (integrations) configured in Home Assistant.

```python
def get_config_entries(ctx: Configuration) -> list[dict[str, Any]]
```

```python
entries = get_config_entries(ctx)
```

--------------------------------

### Install Latest Pre-release with pip

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Install the latest pre-release version of hass-cli directly from the development branch on GitHub.

```bash
$ pip install git+https://github.com/home-assistant-ecosystem/home-assistant-cli@dev
```

--------------------------------

### Install with DNF on Fedora

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Install hass-cli on Fedora systems using the DNF package manager. Note that distribution packages might be outdated.

```bash
$ sudo  dnf -y install home-assistant-cli
```

--------------------------------

### YAML Simple Data Example

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/07-yaml-utilities.md

Demonstrates basic YAML data types including strings, numbers, booleans, and null values.

```yaml
# String
name: "Kitchen Light"

# Number
temperature: 22.5
brightness: 200

# Boolean
active: true
enabled: false

# Null
deprecated: null
```

--------------------------------

### YAML Complex Example

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/07-yaml-utilities.md

A comprehensive example combining various YAML features like nested objects, lists of objects, and complex configurations.

```yaml
name: "Home Automation"
location:
  latitude: 37.7749
  longitude: -122.4194
  timezone: "America/Los_Angeles"

areas:
  - name: Kitchen
    devices:
      - name: "Overhead Light"
        id: light.kitchen_overhead
      - name: "Counter Light"
        id: light.kitchen_counter

automations:
  - id: "morning_routine"
    trigger:
      platform: time
      at: "06:00:00"
    action:
      - service: light.turn_on
        entity_id: light.bedroom
```

--------------------------------

### Install Latest Release with pip

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Use this command to install the latest stable release of hass-cli using pip.

```bash
$ pip install homeassistant-cli
```

--------------------------------

### Install with Homebrew on macOS

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Install hass-cli on macOS using the Homebrew package manager. Distribution releases may be outdated.

```bash
$ brew install homeassistant-cli
```

--------------------------------

### Get Home Assistant Core Info

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Retrieves information about the Home Assistant Core, including version and system details.

```bash
hass-cli ha core info
```

--------------------------------

### Documentation Coverage Summary

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/VERIFICATION.txt

Overview of the documented elements including constants, examples, and overall documentation quality.

```APIDOC
## Documentation Coverage

### Constants Covered:
- CLI constants: 5
- WebSocket API types: 12
- REST API URLs: 11
- HTTP status codes: 13
- Entity states: 28
- Service names: 22
- Entity attributes: 30+
- Measurement units: 60+
- Device classes: 14
- Event types: 15
- Configuration keys: 100+
- **Total Constants: 200+ documented**

### Code Examples:
- **Total Examples: 90+**
- Examples by Category:
  - Authentication: 5
  - State operations: 8
  - Service calls: 6
  - Event handling: 4
  - CLI commands: 30+
  - Output formatting: 8
  - Bash scripting: 12
  - Python integration: 6
  - Error handling: 5
  - Performance optimization: 3
  - Template rendering: 2
  - YAML processing: 6

## Documentation Quality Metrics

### Structure:
- Hierarchical organization (10 main modules)
- Clear section headings
- Cross-references with links
- Table of contents in INDEX
- Navigation in README

### Content:
- Function signatures with full types
- Parameter documentation with tables
- Return type documentation
- Exception/error documentation
- Real-world usage examples
- Integration patterns

### Format:
- Markdown compatible
- Code syntax highlighting
- Consistent formatting
- Proper punctuation
- Grammar checked

### Coverage:
- All public API functions
- All CLI commands
- All exported types
- All constants
- Error handling

## Key Features Documented:
- Configuration management
- Server auto-detection (Zeroconf)
- Authentication methods (3 types)
- REST API integration
- WebSocket API integration
- Supervisor API integration
- Output formatting (5 formats)
- Custom columns
- Error handling and exceptions
- YAML parsing and serialization
- Plugin architecture
- Dynamic command loading
- Shell completion
- HTTP debugging
- Performance optimization
- Scripting patterns
- Automation examples
- Testing patterns

## Verification Summary:

### Status: ✓ COMPLETE

### Objectives Met:
- Analyzed 26 Python source files
- Documented 45+ API functions
- Documented 60+ CLI commands
- Documented 200+ constants
- Provided 90+ code examples
- Generated 4,450+ lines of documentation
- Organized in 10 comprehensive modules
- Created master index (00-INDEX.md)
- Provided navigation guide (README.md)
- Covered architecture (08-project-structure.md)
- Provided usage patterns (09-usage-patterns.md)

### Documentation Types:
- API Reference - Complete
- CLI Reference - Complete
- Constants Reference - Complete
- Exception Reference - Complete
- Usage Patterns - Comprehensive
- Project Architecture - Complete
- Integration Examples - Extensive
- Configuration Guide - Complete

### File Organization:
- 00-INDEX.md - Navigation & overview
- 01-configuration.md - Configuration API
- 02-remote-api.md - Remote API functions
- 03-exceptions.md - Exception handling
- 04-helper-functions.md - Helpers
- 05-cli-commands.md - CLI commands
- 06-constants.md - Constants
- 07-yaml-utilities.md - YAML functions
- 08-project-structure.md - Architecture
- 09-usage-patterns.md - Examples
- README.md - Navigation guide

### Quality Assurance:
- No external content (pure source analysis)
- Accurate type information
- Consistent terminology
- Complete API coverage
- Practical examples
- Error scenarios covered
- Cross-referenced sections
- Professional formatting
```

--------------------------------

### Get Home Assistant Release Version in YAML

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Fetch the Home Assistant release version in YAML format using the '--output=yaml' flag.

```bash
$ hass-cli --output=yaml config release
  -  2026.4.1
```

--------------------------------

### Test Connectivity

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Verify your connection to Home Assistant by running 'hass-cli system info' to get general system details or 'hass-cli raw GET /api/' to test the REST API endpoint.

```bash
hass-cli system info
```

```bash
hass-cli raw GET /api/
```

--------------------------------

### Get Home Assistant Instance Info

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Fetches basic information about the Home Assistant instance, including version and location. Useful for quick status checks.

```python
def get_info(ctx: Configuration) -> dict[str, Any]

Get basic info about the Home Assistant instance.

**Returns:** Dictionary with version, location, unit system, etc.

**Example:**
```python
info = get_info(ctx)
print(f"Version: {info.get('version')}")
```
```

--------------------------------

### Get Single Integration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_config_entry()` to retrieve details about a specific integration (config entry) in Home Assistant.

```python
get_config_entry()            # Get single integration
```

--------------------------------

### Get Home Assistant Release Version

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Retrieve the current release version of your Home Assistant server using the 'config release' command.

```bash
$ hass-cli config release
VERSION
2026.4.1
```

--------------------------------

### Get Available Services

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves a list of all available services in Home Assistant. Useful for discovering service domains and names.

```python
def get_services(ctx: Configuration) -> list[dict[str, Any]]

Get list of all available services.

**Returns:** List of service dictionaries with domain, service name, and description

**Example:**
```python
services = get_services(ctx)
light_services = [s for s in services if s["domain"] == "light"]
```
```

--------------------------------

### Automation with Cron Jobs

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Provides examples of cron job entries to schedule Home Assistant script execution at specific times. Ensure the hass-cli path is correctly configured in your cron environment.

```bash
# /etc/cron.d/home_automation
0 6 * * * hass-cli service call script.morning_routine
0 23 * * * hass-cli service call script.evening_routine
```

--------------------------------

### Get Home Assistant Configuration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves the running configuration dictionary of the Home Assistant instance. Use this to access settings like unit system and location.

```python
def get_config(ctx: Configuration) -> dict[str, Any]

Get the running configuration dictionary.

**Returns:** Configuration structure with unit system, location, etc.

**Example:**
```python
config = get_config(ctx)
print(f"Unit system: {config.get('unit_system')}")
```
```

--------------------------------

### Display Configuration in YAML

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/07-yaml-utilities.md

Show Home Assistant configuration information formatted as YAML using the -o yaml flag.

```bash
# Show config in YAML format
hass-cli -o yaml config info
```

--------------------------------

### Get Entity History with Time Filter

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Retrieve the state history for one or more entities within a specified time frame. This example fetches history for the last 50 minutes.

```bash
$ hass-cli state history --since 50m light.kitchen_light_1 binary_sensor.presence_kitchen
```

--------------------------------

### List Home Assistant Areas

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_areas()` to list all defined areas in your Home Assistant setup. This is useful for organizing and managing devices by location.

```python
get_areas()           # List areas
```

--------------------------------

### JSON and YAML Output Processing with hass-cli

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Process Home Assistant CLI output in JSON or YAML formats using tools like jq for data extraction and manipulation. Examples include getting configuration details and counting entities.

```bash
# Extract specific field using jq
version=$(hass-cli -o json config release | jq -r '.[0]')

# Parse YAML and get value
config=$(hass-cli -o yaml config info)

# Count entities of type
light_count=$(hass-cli -o json state list "^light\." | jq 'length')
echo "Total lights: $light_count"

# List entities with specific state
hass-cli -o json state list | jq '.[] | select(.state=="on") | .entity_id'
```

--------------------------------

### Set Up Development Environment for Home Assistant CLI

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Set up a virtual environment for developing the Home Assistant CLI. This ensures isolation from your system's Python packages.

```bash
python3 -m venv .
$ source bin/activate
$ script/setup
```

--------------------------------

### List Entity States with Custom Columns

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Use the --columns flag to specify which data to display when listing entity states. This example shows how to retrieve entity IDs and all attributes.

```bash
$ hass-cli --columns=ENTITY="entity_id,ATTRIBUTES=attributes[*"]" state list zone
```

--------------------------------

### get_info()

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Fetches basic information about the Home Assistant instance, including version and system settings.

```APIDOC
## get_info()

### Description
Get basic info about the Home Assistant instance.

### Returns
Dictionary with version, location, unit system, etc.

### Example
```python
info = get_info(ctx)
print(f"Version: {info.get('version')}")
```
```

--------------------------------

### List all Home Assistant Integrations

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Lists all configured integrations. Accepts an optional regex filter to narrow down the results.

```bash
hass-cli integration list [FILTER]
```

```bash
hass-cli integration list
```

```bash
hass-cli integration list mqtt
```

--------------------------------

### Initialize Configuration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/01-configuration.md

Creates a new Configuration instance with default values. All configuration attributes are initialized to safe defaults.

```python
def __init__(self) -> None:
    pass
```

--------------------------------

### Call Backup Service

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Initiate a backup creation process by calling the 'backup.create' service. Use 'service list' to find available services.

```bash
$ hass-cli service call backup.create
```

--------------------------------

### Configure Home Assistant CLI Environment Variables

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Set these environment variables if your Home Assistant installation is secured or not running on the default localhost:8123 address. Ensure HASS_SERVER points to your Home Assistant instance and HASS_TOKEN contains a valid long-lived access token.

```bash
export HASS_SERVER=http://homeassistant.local:8123
export HASS_TOKEN=eyJ0eXAiO-----------------------ed8mj0NP8
```

--------------------------------

### Configuration Entry Point with Decorators

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/08-project-structure.md

The `cli()` function is decorated with Click decorators to register global options and configure the CLI class, setting up the main command-line interface.

```python
@click.command(cls=HomeAssistantCli, context_settings=CONTEXT_SETTINGS)
@click_log.simple_verbosity_option(logging.getLogger(), "--loglevel", "-l")
@click.version_option(const.__version__)
# ... more decorators for each option
def cli(ctx: Configuration, ...) -> None:
    """Command line interface for Home Assistant."""
```

--------------------------------

### Get Specific Entity State

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use the 'state get' command followed by the entity ID to fetch the current state of a specific entity.

```bash
hass-cli state get light.kitchen
```

--------------------------------

### Format Data Using Configuration Context

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/04-helper-functions.md

Use format_output as a convenience wrapper around raw_format_output, applying output format settings from a Configuration context. It can optionally use provided columns or default to ctx.columns.

```python
from homeassistant_cli.helper import format_output

states = get_states(ctx)
output = format_output(ctx, states)
ctx.echo(output)
```

--------------------------------

### Home Assistant CLI Global Options

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Demonstrates the general structure for using global options with Home Assistant CLI commands. These options are applied before the command itself.

```bash
hass-cli [GLOBAL_OPTIONS] COMMAND
```

--------------------------------

### Graceful Error Handling for Hass CLI State Get

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Implement a safe function to get entity state, handling errors by returning a default value and suppressing stderr output.

```bash
#!/bin/bash

get_state_safe() {
    local entity=$1
    local default=$2
    
    if result=$(hass-cli -o json state get "$entity" 2>/dev/null); then
        echo "$result" | jq -r '.state'
    else
        echo "${default:-"unknown"}"
    fi
}

# Usage
temp=$(get_state_safe "sensor.temperature" "unknown")
echo "Temperature: $temp"
```

--------------------------------

### Configuration Class Constructor

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/01-configuration.md

Initializes a new Configuration instance with default settings. This is the entry point for managing CLI configuration.

```APIDOC
## Constructor

```python
def __init__(self) -> None
```

Creates a new Configuration instance with default values. All configuration attributes are initialized to safe defaults.
```

--------------------------------

### get_state()

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Get the current state of a single entity.

```APIDOC
## get_state()

### Description
Get the current state of a single entity.

### Parameters
- `entity_id` (str): Entity ID (e.g., "light.kitchen")

### Returns
State dictionary, or None if entity not found

### Example
```python
state = get_state(ctx, "light.kitchen")
if state:
    print(f"State: {state['state']}")
    print(f"Brightness: {state['attributes'].get('brightness')}")
```
```

--------------------------------

### get_config()

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves the entire running configuration dictionary of the Home Assistant instance.

```APIDOC
## get_config()

### Description
Get the running configuration dictionary.

### Returns
Configuration structure with unit system, location, etc.

### Example
```python
config = get_config(ctx)
print(f"Unit system: {config.get('unit_system')}")
```
```

--------------------------------

### Show CLI Information

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Displays information about the Home Assistant CLI itself, including its version and configuration.

```bash
hass-cli info
```

--------------------------------

### Get Entity State

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Retrieves the current state of a specific entity, with options for YAML or JSON output.

```APIDOC
## Get Entity State

### Description
Retrieves the current state of a specific entity, with options for YAML or JSON output.

### Command
```bash
hass-cli state get <ENTITY_ID>
```

### Options
- `-o <format>` or `--output-format <format>`: Specify output format (e.g., `yaml`, `json`).

### Example
```bash
$ hass-cli -o yaml state get light.guestroom_light
```
```

--------------------------------

### Control Light State Using State Constants

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/06-constants.md

Utilize `hass.SERVICE_TURN_ON` and `hass.STATE_ON` constants to control and check the state of lights. Ensure `get_state` is imported or available in the scope.

```python
import homeassistant_cli.hassconst as hass
from homeassistant_cli.remote import call_service

# Turn on a light
call_service(ctx, "light", hass.SERVICE_TURN_ON, {
    "entity_id": "light.kitchen",
    "brightness": 255
})

# Check if light is on
state = get_state(ctx, "light.kitchen")
if state["state"] == hass.STATE_ON:
    print("Light is on")
```

--------------------------------

### Home Assistant CLI Directory Structure

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/08-project-structure.md

Illustrates the modular plugin architecture and file organization of the Home Assistant CLI project.

```tree
homeassistant_cli/
├── __init__.py                 # Package initialization
├── cli.py                       # Main CLI entry point and HomeAssistantCli class
├── config.py                    # Configuration class and server resolution
├── const.py                     # CLI constants
├── exceptions.py                # Exception classes
├── hassconst.py                 # Home Assistant constants
├── helper.py                    # Output formatting utilities
├── yaml.py                      # YAML parsing utilities
├── remote.py                    # REST and WebSocket API wrapper
├── autocompletion.py            # Shell autocompletion support
├── plugins/                     # Command plugins
│   ├── __init__.py
│   ├── area.py                 # Area management commands
│   ├── config.py               # Configuration commands
│   ├── device.py               # Device management commands
│   ├── discover.py             # Network discovery commands
│   ├── entity.py               # Entity management commands
│   ├── event.py                # Event commands
│   ├── ha.py                   # Home Assistant OS commands
│   ├── info.py                 # CLI info commands
│   ├── integration.py          # Config entry commands
│   ├── map.py                  # Map display commands
│   ├── raw.py                  # Raw API commands
│   ├── service.py              # Service call commands
│   ├── state.py                # State management commands
│   ├── system.py               # System info commands
│   ├── template.py             # Template rendering commands
│   └── completion.py           # Shell completion commands

```

--------------------------------

### Get Single Entity Information

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves detailed registry information for a specific entity using its entity ID.

```python
def get_entity(ctx: Configuration, entity_id: str) -> list[dict[str, Any]]

Get registry information for a single entity.

**Parameters:**
- `entity_id` (str): Entity ID

**Returns:** Entity registry ID or list

**Example:**
```python
entity_id = get_entity(ctx, "light.kitchen")
```
```

--------------------------------

### Discover Instances

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Discovers Home Assistant instances on the local network.

```APIDOC
## discover

### Description
Discover Home Assistant instances on the local network.

### Command
hass-cli discover

### Output
List of discovered instances with URLs

### Example
```bash
hass-cli discover
```
```

--------------------------------

### Create YAML Parser

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/07-yaml-utilities.md

Instantiate a YAML parser object from the Configuration. This is the first step before loading or dumping YAML.

```python
ctx.yaml() -> YAML
```

```python
yamlp = ctx.yaml()
```

--------------------------------

### Get State History

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Retrieves the history of state changes for one or more entities within a specified time range.

```APIDOC
## Get State History

### Description
Retrieves the history of state changes for one or more entities within a specified time range.

### Command
```bash
hass-cli state history [--since <TIME>] <ENTITY_ID1> [ENTITY_ID2] ...
```

### Options
- `--since <TIME>`: Specify the time since which to retrieve history (e.g., `50m`).
- `--sort-by <FIELD>`: Sort the results by a specific field (e.g., `last_changed`).

### Example
```bash
$ hass-cli state history --since 50m light.kitchen_light_1 binary_sensor.presence_kitchen
```

### Example with sorting
```bash
$ hass-cli --sort-by last_changed state history --since 50m light.kitchen_light_1 binary_sensor.presence_kitchen
```
```

--------------------------------

### List Available Services

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_services()` to retrieve a list of all available services that can be called in Home Assistant. This is useful for discovering what actions can be performed.

```python
get_services()        # List available services
```

--------------------------------

### Get Home Assistant Error Log

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Fetches the raw text content of the Home Assistant error log. Useful for debugging.

```python
def get_raw_error_log(ctx: Configuration) -> str

Get the error log from Home Assistant.

**Returns:** Error log text

**Example:**
```python
error_log = get_raw_error_log(ctx)
print(error_log)
```
```

--------------------------------

### Get Event Listeners

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves a dictionary of all currently registered event listeners in Home Assistant. Useful for debugging event handling.

```python
def get_event_listeners(ctx: Configuration) -> dict

Get list of currently registered event listeners.

**Returns:** Dictionary of event listeners

**Example:**
```python
listeners = get_event_listeners(ctx)
```
```

--------------------------------

### Main CLI Class for Plugin Loading

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/08-project-structure.md

The `HomeAssistantCli` class inherits from `click.MultiCommand` to enable dynamic loading of commands from plugins.

```python
class HomeAssistantCli(click.MultiCommand):
    def list_commands(self, ctx: Context) -> list[str]:
        """List all command available as plugin."""
    
    def get_command(self, ctx: Context, cmd_name: str) -> Group | Command | None:
        """Import the commands of the plugins."""
```

--------------------------------

### Call Services with Arguments

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Execute Home Assistant services with various argument types, including simple key-value pairs and complex JSON-like structures.

```bash
# Turn on light with specific brightness
hass-cli service call light.turn_on --arguments entity_id=light.kitchen,brightness=200
```

```bash
# Toggle multiple entities
hass-cli service call homeassistant.toggle --arguments entity_id=light.office
```

```bash
# Call with complex parameters
hass-cli service call light.turn_on --arguments \
  entity_id=light.scene,\
  effect=pulse,\
  transition=2,\
  color_name=red
```

--------------------------------

### Get Event Types

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves a dictionary of all available event types in Home Assistant. Useful for understanding what events can be fired or listened to.

```python
def get_events(ctx: Configuration) -> dict[str, Any]

Get list of all available event types.

**Returns:** Dictionary of event types with metadata

**Example:**
```python
events = get_events(ctx)
```
```

--------------------------------

### Get Home Assistant Supervisor Info

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Retrieves information about the Home Assistant supervisor. Requires the HASS_SUPERVISOR_TOKEN environment variable to be set.

```bash
hass-cli ha supervisor info
```

--------------------------------

### Package and Version Constants

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/06-constants.md

Defines the package name and version for the Home Assistant CLI.

```python
PACKAGE_NAME = "homeassistant_cli"
__version__ = "1.0.1"
```

--------------------------------

### Get State History

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_history()` to retrieve the historical data for entity states. This is valuable for analyzing trends and past events.

```python
get_history()         # Get state history
```

--------------------------------

### Listen for All Events

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Listens for and displays all events occurring in Home Assistant in real-time.

```bash
hass-cli event listen
```

```bash
hass-cli event listen
```

--------------------------------

### State-based Automation Script

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Implement state-based automation by checking entity states and triggering services. This script turns on a light if the front door is open.

```bash
#!/bin/bash
# Check if door is open and turn on light

door_state=$(hass-cli -o json state get binary_sensor.front_door | jq -r '.state')

if [ "$door_state" = "on" ]; then
    # Door is open, turn on light
    hass-cli service call light.turn_on --arguments entity_id=light.entryway
    echo "Front door opened, light activated"
fi
```

--------------------------------

### Retrieve All Devices

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Use this function to get a list of all devices registered in Home Assistant. The returned list contains dictionaries with device details.

```python
def get_devices(ctx: Configuration) -> list[dict[str, Any]]

Retrieve all devices.

**Returns:** List of device dictionaries with ID, name, model, manufacturer, etc.

**Example:**
```python
devices = get_devices(ctx)
```
```

--------------------------------

### Configure Environment Variables for Server and Token

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Set HASS_SERVER and HASS_TOKEN environment variables for persistent authentication with your Home Assistant instance.

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

--------------------------------

### hass-cli state get

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Retrieves the current state of a single entity. The entity ID supports autocompletion and the output can be formatted as a table or JSON.

```APIDOC
## hass-cli state get

### Description
Get the current state of a single entity. Supports autocompletion for the entity ID and can output in table or JSON format.

### Method
CLI Command

### Endpoint
`hass-cli state get ENTITY`

### Parameters
#### Arguments
- `ENTITY` (string) - Required - Entity ID (supports autocompletion)

### Output
Entity state details in table or JSON format.

### Example
```bash
hass-cli state get light.kitchen
hass-cli -o yaml state get light.kitchen
```
```

--------------------------------

### List All Entities

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Execute the 'state list' command to retrieve a list of all entities in your Home Assistant instance.

```bash
hass-cli state list
```

--------------------------------

### YAML Nested Structures Example

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/07-yaml-utilities.md

Illustrates how to create nested data structures in YAML, such as dictionaries within dictionaries or lists within dictionaries.

```yaml
rooms:
  kitchen:
    temperature: 22.5
    lights:
      - light.overhead
      - light.counter
  bedroom:
    temperature: 20.0
    lights:
      - light.main
      - light.bedside
```

--------------------------------

### Discover Home Assistant Instances

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Discovers Home Assistant instances on the local network. This command outputs a list of discovered instances with their URLs.

```bash
hass-cli discover
```

--------------------------------

### Get Specific Config Entry

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Fetch details for a single configuration entry using its unique ID. Requires the entry ID as a string parameter.

```python
def get_config_entry(ctx: Configuration, entry_id: str) -> dict[str, Any]
```

```python
entry = get_config_entry(ctx, "entry_abc123")
```

--------------------------------

### Declarative Area and Device Configuration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Manage Home Assistant configuration declaratively by creating areas and assigning devices using 'hass-cli area create' and 'hass-cli device assign'.

```bash
#!/bin/bash
# Declarative area and device configuration

# Define desired state
areas=("Kitchen" "Bedroom" "Living Room")
devices=(
    "Kitchen|light.overhead"
    "Kitchen|light.counter"
    "Bedroom|light.main"
)

# Create areas
for area in "${areas[@]}"; do
    hass-cli area create "$area" 2>/dev/null || true
done

# Assign devices
for config in "${devices[@]}"; do
    IFS='|' read -r area device <<< "$config"
    hass-cli device assign "$area" "$device"
done
```

--------------------------------

### Get All Areas

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves a list of all area definitions from the Home Assistant configuration. Each area is returned as a dictionary containing its ID, name, and an optional picture.

```python
def get_areas(ctx: Configuration) -> list[dict[str, Any]]:
    """Retrieve all area definitions."""
    ...

areas = get_areas(ctx)
for area in areas:
    print(f"{area['name']} ({area['area_id']})")
```

--------------------------------

### Get Home Assistant System Health

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_health()` to retrieve the health status of your Home Assistant instance. This can help in diagnosing potential issues.

```python
get_health()          # Get system health
```

--------------------------------

### Command-Line Entry Point Function

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/08-project-structure.md

The `run()` function serves as the main entry point for the `hass-cli` script, handling argument parsing, context creation, plugin loading, and command execution.

```python
# In homeassistant_cli/cli.py
def run() -> None:
    """Run entry point."""
    # Exception handling and Click invocation
```

--------------------------------

### Get Single Entity State

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_state()` to retrieve the state of a specific entity. This is useful when you need to check the status of an individual device or sensor.

```python
get_state()           # Get single entity state
```

--------------------------------

### List Home Assistant Devices

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_devices()` to retrieve a list of all devices configured in Home Assistant. This provides an overview of your connected hardware.

```python
get_devices()         # List devices
```

--------------------------------

### Get Home Assistant States

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/00-INDEX.md

Use `get_states()` to retrieve all entity states from Home Assistant. This is a fundamental operation for monitoring the status of your devices and entities.

```python
get_states()           # Get all entity states
```

--------------------------------

### Configuration Class Methods

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/VERIFICATION.txt

Documentation coverage for methods within the Configuration class.

```APIDOC
## Configuration Class Methods

### Description
This section details the documented methods available on the Configuration class.

### Methods
- **resolve_server()**: Documented module function for resolving the server.
- **set_supervisor_server()**: Documented module function for setting the supervisor server.
- **echo()**: Documented method for echoing configuration.
- **log()**: Documented method for logging configuration.
- **vlog()**: Documented method for verbose logging of configuration.
- **resolve_server()**: Documented method for resolving the server within the Configuration class.
- **set_supervisor_server()**: Documented method for setting the supervisor server within the Configuration class.
- **auto_output()**: Documented method for automatic output configuration.
- **yaml()**: Documented method for YAML configuration handling.
- **yamlload()**: Documented method for loading YAML configuration.
- **yamldump()**: Documented method for dumping YAML configuration.
```

--------------------------------

### yaml()

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/07-yaml-utilities.md

Creates and returns a default YAML parser instance configured for Home Assistant CLI. This parser is set to 'safe' mode, uses a pure Python implementation, preserves quotes, and defaults to block style for YAML output.

```APIDOC
## yaml()

### Description
Create and return a default YAML parser instance with Home Assistant CLI configuration.

### Returns
- Configured `YAML` parser object

### Configuration
- Type: "safe" (no arbitrary Python object execution)
- Pure Python implementation
- Preserves quotes in YAML
- Default flow style: False (block style preferred)

### Example
```python
from homeassistant_cli.yaml import yaml

yamlp = yaml()
```
```

--------------------------------

### Run hass-cli with Docker

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Execute hass-cli using a Docker container if you don't have a Python setup. This method may not support file system access.

```bash
$ docker run homeassistant/home-assistant-cli
```

--------------------------------

### Batch Operations with Hass CLI and JQ

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Fetch all data at once using 'state list' and process with 'jq' for efficiency, instead of making N+1 requests in a loop.

```bash
# Get all data at once
hass-cli -o json state list | jq '.[] | select(.state=="on")'
```

```bash
# Instead of looping
for entity in $(hass-cli service list | ...); do
    hass-cli state get "$entity"  # Slow: N+1 requests
done
```

--------------------------------

### Render Jinja2 Templates with Home Assistant CLI

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Renders Jinja2 templates, optionally providing data from a YAML/JSON file. The `--local` flag enables client-side rendering.

```bash
hass-cli template TEMPLATEPATH [DATAPATH] [--local]
```

```bash
hass-cli template motionlight.yaml.j2 motiondata.yaml
```

```bash
hass-cli template lovelace-template.yaml --local
```

--------------------------------

### Validate Home Assistant Configuration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Validates the Home Assistant configuration files using the CLI.

```bash
hass-cli config validate
```

```bash
hass-cli config validate
```

--------------------------------

### Assign Area to Device

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Use this function to associate a device with a specific area within your Home Assistant setup. Requires both the device ID and the area ID.

```python
def assign_area(ctx: Configuration, device_id: str, area_id: str) -> dict[str, Any]

Assign an area to a device.

**Parameters:**
- `device_id` (str): Device ID
- `area_id` (str): Area ID

**Returns:** Result dictionary

**Example:**
```python
assign_area(ctx, "device_123", "area_kitchen")
```
```

--------------------------------

### List Devices and Areas with hass-cli

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Use `hass-cli device list` to view all registered devices and `hass-cli area list` to see available areas. These commands help in managing and organizing your Home Assistant devices.

```bash
$ hass-cli device list
```

```bash
ID                                NAME                           MODEL                            MANUFACTURER        AREA
   a3852c3c3ebd47d3acac195478ca6f8b  Basement stairs motion         SML001                           Philips             c6c962b892064a218e968fcaee7950c8
   880a944e74db4bb48ea3db6dd24af357  Basement Light 2               TRADFRI bulb GU10 WS 400lm       IKEA of Sweden      c6c962b892064a218e968fcaee7950c8
   657c3cc908594479aab819ff80d0c710  Office                         Hue white lamp                   Philips             None
   [...]
```

```bash
$ hass-cli area list
```

```bash
ID                                NAME
   295afc88012341ecb897cd12d3fbc6b4  Bathroom
   9e08d89203804d5db995c3d0d5dbd91b  Winter Garden
   8816ee92b7b84f54bbb30a68b877e739  Office
   [...]
```

--------------------------------

### hass-cli state history

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Retrieves the state change history for specified entities within a given time range. Supports filtering by start and end times.

```APIDOC
## hass-cli state history

### Description
Get state change history for entities within a specified time range.

### Method
CLI Command

### Endpoint
`hass-cli state history [--since SINCE] [--until UNTIL] ENTITY...`

### Parameters
#### Arguments
- `ENTITY` (string) - One or more - Entity IDs to get history for.

#### Options
- `--since` (string) - Start time (e.g., "50m", "2h", "1d").
- `--until` (string) - End time.

### Output
Historical state records.

### Example
```bash
hass-cli state history --since 50m light.kitchen binary_sensor.motion
hass-cli -o yaml state history light.kitchen
```
```

--------------------------------

### Get Home Assistant History

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves historical state changes for specified entities or all entities within a given time range. Requires importing `datetime` and `timedelta`.

```python
from datetime import datetime, timedelta

def get_history(
    ctx: Configuration,
    entities: list | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
) -> list[dict[str, Any]]

Get state change history for entities.

**Parameters:**
- `entities` (list | None): List of entity IDs, or None for all
- `start_time` (datetime | None): Start timestamp
- `end_time` (datetime | None): End timestamp

**Returns:** List of historical state records

**Example:**
```python
now = datetime.now()
history = get_history(ctx, 
    entities=["light.kitchen"],
    start_time=now - timedelta(hours=1),
    end_time=now
)
```
```

--------------------------------

### Display Help Information for hass-cli

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/README.rst

Use this command to display the help message and understand the available options and commands for the Home Assistant CLI.

```bash
$ hass-cli --help
Usage: hass-cli [OPTIONS] COMMAND [ARGS]...

Command line interface for Home Assistant.

Options:
  -l, --loglevel LVL              Either CRITICAL, ERROR, WARNING, INFO or
                                   DEBUG
  --version                       Show the version and exit.
  -s, --server TEXT               The server URL or `auto` for automatic
                                   detection. Can also be set with the
                                   environment variable HASS_SERVER.  [default:
                                   auto]
  --token TEXT                    The Bearer token for Home Assistant
                                   instance. Can also be set with the
                                   environment variable HASS_TOKEN.
  --supervisor-token TEXT         The Bearer token for Home Assistant
                                   supervisor. Can also be set with the
                                   environment variable HASS_SUPERVISOR_TOKEN.
  --password TEXT                 The API password for Home Assistant
                                   instance. Can also be set with the
                                   environment variable HASS_PASSWORD.
  --timeout INTEGER               Timeout for network operations.  [default:
                                   5]
  -o, --output [json|yaml|table|auto|ndjson]
                                    Output format.  [default: auto]
  -v, --verbose                   Enables verbose mode.
  -x                              Print backtraces when exception occurs.
  --cert TEXT                     Path to client certificate file (.pem) to
                                   use when connecting.
  --insecure                      Ignore SSL Certificates. Allow to connect to
                                   servers with self-signed certificates. Be
                                   careful!
  --debug                         Enables debug mode.
  --columns TEXT                  Custom columns key=value list. Example:
                                    ENTITY=entity_id,
                                    NAME=attributes.friendly_name
  --no-headers                    When printing tables don't use headers
                                    (default: print headers)
  --table-format TEXT             Which table format to use.
  --sort-by TEXT                  Sort table by the jsonpath expression.
                                    Example: last_changed
  --help                          Show this message and exit.

Commands:
  area         Get info and operate on areas from Home Assistant...
  config       Get configuration from a Home Assistant instance.
  device       Get info and operate on devices from Home Assistant.
  discover     Discovery for the local network.
  entity       Get info on entities from Home Assistant.
  event        Interact with events.
  ha           Home Assistant Operating System commands.
  info         Show information about Home Assistant CLI.
  integration  Get info and operate on integrations (config entries) from...
  map          Show the location of the config or an entity on a map.
  raw          Call the raw API (advanced).
  service      Call and work with services.
  state        Get info on entity state from Home Assistant.
  system       System details and operations for Home Assistant.
  template     Render templates on server or locally.

```

--------------------------------

### Get All Entity States

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieve all entity states from Home Assistant using `get_states`. The function returns a list of dictionaries, each representing an entity's state and attributes.

```python
states = get_states(ctx)
lights = [s for s in states if s["entity_id"].startswith("light.")]
```

--------------------------------

### Get Single Entity State

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Retrieve the current state details for a specific entity. Supports autocompletion for entity IDs and allows output in table or JSON format.

```bash
hass-cli state get light.kitchen
```

```bash
hass-cli -o yaml state get light.kitchen
```

--------------------------------

### get_services

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieves a list of all available services in Home Assistant.

```APIDOC
## get_services()

### Description
Get list of all available services.

### Returns
List of service dictionaries with domain, service name, and description

### Example
```python
services = get_services(ctx)
light_services = [s for s in services if s["domain"] == "light"]
```
```

--------------------------------

### Validate Hass CLI Connection and Configuration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Test API connectivity with 'raw GET /api/', check authentication with 'system info', and validate configuration with 'config validate'.

```bash
# Test API connectivity
hass-cli raw GET /api/
```

```bash
# Check authentication
hass-cli system info
```

```bash
# Validate config
hass-cli config validate
```

--------------------------------

### Handle HomeAssistantCliError in API Operations

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/03-exceptions.md

Example of catching a HomeAssistantCliError when making an API call that might fail due to network issues, invalid responses, or authentication problems.

```python
from homeassistant_cli.exceptions import HomeAssistantCliError
from homeassistant_cli.remote import restapi

try:
    response = restapi(ctx, "GET", "/api/states/invalid.entity")
except HomeAssistantCliError as e:
    print(f"API error: {e}")
```

--------------------------------

### format_output()

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/04-helper-functions.md

A convenience wrapper around `raw_format_output` that utilizes settings from a Configuration context for formatting.

```APIDOC
## format_output()

### Description
Format data using settings from the Configuration context. Convenience wrapper around `raw_format_output()`.

### Parameters:
- `ctx` (Configuration) - Required - Configuration context with output format settings
- `data` (list[dict]) - Required - Data to format
- `columns` (list | None) - Optional - Table columns (uses ctx.columns if None)

### Returns:
Formatted string

### Example:
```python
from homeassistant_cli.helper import format_output

states = get_states(ctx)
output = format_output(ctx, states)
ctx.echo(output)
```
```

--------------------------------

### Validate System Configuration

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Validates the Home Assistant system configuration. No additional options are required.

```bash
hass-cli system validate
```

--------------------------------

### Get Entity State History

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Retrieve the state change history for one or more entities. You can specify a time range using `--since` and `--until` options. Output can be customized.

```bash
hass-cli state history --since 50m light.kitchen binary_sensor.motion
```

```bash
hass-cli -o yaml state history light.kitchen
```

--------------------------------

### Get Home Assistant System Health

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/02-remote-api.md

Retrieve detailed system health information from your Home Assistant instance. This function returns a dictionary containing various health check results.

```python
health = get_health(ctx)
```

--------------------------------

### List Devices with hass-cli

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/05-cli-commands.md

Lists all devices in Home Assistant. An optional regex can filter the results by device name. Supports sorting.

```bash
hass-cli device list [DEVICEFILTER]
```

```bash
hass-cli device list
```

```bash
hass-cli device list "Kitchen"
```

```bash
hass-cli --sort-by name device list
```

--------------------------------

### Integration Test Light Control

Source: https://github.com/home-assistant-ecosystem/home-assistant-cli/blob/dev/_autodocs/09-usage-patterns.md

Conduct integration testing for device control, such as turning a light on and verifying its state change using 'hass-cli service call' and 'hass-cli state get'.

```python
import subprocess
import json
import time

def test_light_control():
    # Turn on light
    result = subprocess.run(
        ['hass-cli', 'service', 'call', 'light.turn_on',
         '--arguments', 'entity_id=light.test'],
        capture_output=True
    )
    assert result.returncode == 0, "Failed to turn on light"
    
    # Wait for state update
    time.sleep(1)
    
    # Verify state
    state = subprocess.run(
        ['hass-cli', '-o', 'json', 'state', 'get', 'light.test'],
        capture_output=True,
        text=True
    )
    data = json.loads(state.stdout)
    assert data['state'] == 'on', "Light state is not on"
    
    print("✓ Light control test passed")
```