🏠 Home Assistant CLI

A powerful command-line interface for controlling your Home Assistant instance. Control lights, switches, monitor energy usage, and query entity states directly from your terminal.

Quick Start

# Install
git clone https://github.com/Ajp121/ha-cli.git && cd ha-cli
pip install -r requirements.txt && pip install -e .

# Configure
ha configure  # Enter your HA URL and token

# Use it!
ha light list
ha light on bedroom --brightness 50
ha energy status

Features

• 🔧 Easy Setup: Interactive configuration wizard on first run
• 💡 Light Control: Turn lights on/off, adjust brightness, set colors
• 🔌 Switch Control: Control switches with simple commands
• ⚡ Energy Monitoring: Monitor power usage and energy consumption
• 📊 State Queries: View and monitor entity states
• 💾 Persistent Config: Stores your HA URL and token securely
• 🎨 Color Output: Beautiful, color-coded terminal output
• 🧪 Tested: Comprehensive test suite included

Installation

Prerequisites

• Python 3.7 or higher
• Home Assistant instance with API access
• Long-lived access token from Home Assistant

Quick Install

# Clone the repository
git clone https://github.com/Ajp121/ha-cli.git
cd ha-cli

# Install dependencies
pip install -r requirements.txt

# Install the CLI tool
pip install -e .

This installs the ha command globally on your system.

Note: If the ha command isn't found after installation, you may need to add Python's Scripts directory to your PATH, or use:

python -m ha_cli.cli --help

Alternative: Run without installation

python -m ha_cli.cli --help

Configuration

Getting a Long-Lived Access Token

1. Log into your Home Assistant web interface
2. Click on your username in the bottom left
3. Scroll to the bottom and click "Create Token" under "Long-Lived Access Tokens"
4. Give it a name (e.g., "CLI Tool") and click "OK"
5. Copy the token (you won't be able to see it again!)

First-Time Setup

Run the configuration command:

ha configure

You'll be prompted for:

• Home Assistant URL: e.g., http://homeassistant.local:8123 or http://192.168.1.100:8123
• Access Token: Your long-lived access token from above

The tool will test the connection and save your configuration to ~/.ha-cli/config.json.

Usage

Light Commands

Turn on a light:

ha light on living_room
ha light on light.bedroom

Turn on with brightness (0-100%):

ha light on living_room --brightness 50
ha light on living_room -b 75

Turn on with color:

ha light on living_room --color red
ha light on living_room --color "255,128,0"  # RGB format

Supported color names: red, green, blue, white, yellow, orange, purple

Turn off a light:

ha light off living_room

List all lights:

ha light list                    # Available lights only
ha light list --all              # Include unavailable
ha light list --filter bedroom   # Filter by name

Switch Commands

Turn on a switch:

ha switch on plug_1
ha switch on switch.coffee_maker

Turn off a switch:

ha switch off plug_1

List all switches:

ha switch list                   # Available switches only
ha switch list --all             # Include unavailable
ha switch list --filter kitchen  # Filter by name

State Commands

Get state of a specific entity:

ha state get light.living_room
ha state get sensor.temperature

List all entities:

ha state list

List entities by domain:

ha state list --domain light
ha state list --domain sensor

Filter by name:

ha state list --filter bedroom
ha state list --all  # Include unavailable entities

Energy Commands

Quick energy overview:

ha energy status

Current power usage:

ha energy power                  # All circuits and devices
ha energy power --circuit 5      # Specific circuit only

Today's energy consumption:

ha energy today                  # All circuits
ha energy today --circuit 1      # Specific circuit

General Commands

Reconfigure connection:

ha configure

Get help:

ha --help
ha light --help
ha switch --help
ha energy --help

Examples

# Turn on bedroom light at 30% brightness
ha light on bedroom -b 30

# Turn on living room with warm white color
ha light on living_room --color "255,200,150"

# Check if coffee maker is on
ha state get switch.coffee_maker

# List all available lights (hides unavailable)
ha light list

# See your current power usage
ha energy status

# Check power draw on specific circuit
ha energy power --circuit 5

# Turn off lights
ha light off bedroom_main
ha light off bedroom_side

Configuration File

Configuration is stored in ~/.ha-cli/config.json:

{
  "url": "http://homeassistant.local:8123",
  "token": "your-long-lived-access-token"
}

Troubleshooting

"Unable to connect" error

• Verify your Home Assistant is running and accessible
• Check the URL is correct (include http:// or https://)
• Ensure you're on the same network as your Home Assistant instance

"Invalid access token" error

• Generate a new long-lived access token
• Run ha configure again with the new token

Entity not found

• Check the entity ID exists in Home Assistant
• Entity IDs are case-sensitive
• You can omit the domain prefix (e.g., use bedroom instead of light.bedroom)

Development

Project Structure

ha-cli/
├── ha_cli/
│   ├── __init__.py
│   ├── cli.py           # Main CLI commands
│   ├── config.py        # Configuration management
│   ├── ha_api.py        # Home Assistant API client
│   ├── entities.py      # Entity formatting utilities
│   └── setup.py         # Setup utilities
├── requirements.txt
├── setup.py
└── README.md

Running Tests

# Install test dependencies
pip install -r requirements.txt

# Run all tests
pytest

# Run with coverage report
pytest --cov=ha_cli

# Run specific test file
pytest tests/test_entities.py

See tests/README.md for more details.

License

MIT License - feel free to use and modify as needed!

Contributing

Contributions welcome! This is a personal project but feel free to fork and customize for your needs.

Future Enhancements

Potential features to add:

• Scene activation
• Automation triggering
• Climate control
• Media player control
• Notification sending
• Bulk operations
• Interactive TUI mode