moltbot-ha

# Home Assistant Control

Control your smart home via Home Assistant API using the `moltbot-ha` CLI tool.

## Setup

### 1. Install moltbot-ha
```bash
uv tool install moltbot-ha
```

### 2. Initialize Configuration
```bash
moltbot-ha config init
```

The setup will interactively ask for:
- Home Assistant URL (e.g., `http://192.168.1.100:8123`)
- Token storage preference (environment variable recommended)

### 3. Set Environment Variable
Set your Home Assistant long-lived access token:
```bash
export HA_TOKEN="your_token_here"
```

To create a token:
1. Open Home Assistant → Profile (bottom left)
2. Scroll to "Long-Lived Access Tokens"
3. Click "Create Token"
4. Copy the token and set as `HA_TOKEN` environment variable

### 4. Test Connection
```bash
moltbot-ha test
```

## Discovery Commands

### List All Entities
```bash
moltbot-ha list
```

### List by Domain
```bash
moltbot-ha list light
moltbot-ha list switch
moltbot-ha list cover
```

### Get Entity State
```bash
moltbot-ha state light.kitchen
moltbot-ha state sensor.temperature_living_room
```

## Action Commands

### Turn On/Off
```bash
# Turn on
moltbot-ha on light.living_room
moltbot-ha on switch.coffee_maker

# Turn off
moltbot-ha off light.bedroom
moltbot-ha off switch.fan

# Toggle
moltbot-ha toggle light.hallway
```

### Set Attributes
```bash
# Set brightness (percentage)
moltbot-ha set light.bedroom brightness_pct=50

# Set color temperature
moltbot-ha set light.office color_temp=300

# Multiple attributes
moltbot-ha set light.kitchen brightness_pct=80 color_temp=350
```

### Call Services
```bash
# Activate a scene
moltbot-ha call scene.turn_on entity_id=scene.movie_time

# Set thermostat temperature
moltbot-ha call climate.set_temperature entity_id=climate.living_room temperature=21

# Close cover (blinds, garage)
moltbot-ha call cover.close_cover entity_id=cover.garage
```

### Generic Service Call
```bash
# With parameters
moltbot-ha call automation.trigger entity_id=automation.morning_routine

#...

# moltbot-ha 🏠

**Home Assistant control CLI for Moltbot agents and humans.**

Control your smart home via Home Assistant REST API with powerful safety features, configurable confirmations, and agent-friendly design.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

## ✨ Features

- 🎮 **Full Control**: Lights, switches, covers, scenes, climate, and all Home Assistant domains
- 🛡️ **Safety First**: 3-level safety system with confirmations for critical actions (locks, alarms, garage doors)
- 🤖 **Agent-Friendly**: Designed for AI agents with clear error messages and confirmation workflows
- ⚙️ **Configurable**: Flexible allowlist/blocklist, custom critical domains, logging
- 🚀 **Fast**: Direct REST API calls with retry logic and connection pooling
- 📊 **Output Formats**: Human-readable tables or JSON for programmatic use

---

## 📦 Installation

### Via uv (recommended)
```bash
uv tool install moltbot-ha
```

### Via pip
```bash
pip install moltbot-ha
```

### From source (development)
```bash
git clone https://github.com/iamvaleriofantozzi/moltbot-ha.git
cd moltbot-ha
uv tool install .
```

---

## 🚀 Quick Start

### 1. Initialize Configuration
```bash
moltbot-ha config init
```

The interactive setup will ask you:
- **Home Assistant URL**: Your HA instance URL (e.g., `http://192.168.1.100:8123`)
- **Token storage**: Environment variable (recommended) or config file

### 2. Set Token (if using environment variable)
```bash
export HA_TOKEN="your_long_lived_access_token"
```

**How to create a token:**
1. Open Home Assistant → Profile (bottom left icon)
2. Scroll down to "Long-Lived Access Tokens"
3. Click "Create Token", give it a name (e.g., "moltbot-ha")
4. Copy the token immediately (you can't see it again!)

### 3. Test Connection
```bash
moltbot-ha test
```

You should see:
```
✓ Connected...