Home Assistant Control

Control your smart home via Home Assistant API using the

moltbot-ha

CLI tool.

Setup

1. Install moltbot-ha

uv tool install moltbot-ha

2. Initialize Configuration

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:

export HA_TOKEN="your_token_here"

To create a token:

Open Home Assistant → Profile (bottom left)
Scroll to "Long-Lived Access Tokens"
Click "Create Token"
Copy the token and set as
```
HA_TOKEN
```
environment variable

4. Test Connection

moltbot-ha test

Discovery Commands

List All Entities

moltbot-ha list

List by Domain

moltbot-ha list light
moltbot-ha list switch
moltbot-ha list cover

Get Entity State

moltbot-ha state light.kitchen
moltbot-ha state sensor.temperature_living_room

Action Commands

Turn On/Off

# 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

# 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

# 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

# With parameters
moltbot-ha call automation.trigger entity_id=automation.morning_routine
With JSON data

moltbot-ha call script.turn_on --json '{"entity_id": "script.bedtime", "variables": {"brightness": 10}}'

Safety & Confirmations

moltbot-ha implements a 3-level safety system to prevent accidental actions:

Safety Level 3 (Default - Recommended)

Critical operations require explicit confirmation:

lock.*: Door locks
alarm_control_panel.*: Security alarms
cover.*: Garage doors, blinds

How Confirmation Works

Attempt critical action:

moltbot-ha on cover.garage

Tool returns error:

⚠️  CRITICAL ACTION REQUIRES CONFIRMATION
Action: turn_on on cover.garage
This is a critical operation that requires explicit user approval.
Ask the user to confirm, then retry with --force flag.

Example: moltbot-ha on cover.garage --force

Agent sees this error and asks you:

"Opening the garage door is a critical action. Do you want to proceed?"

You confirm:

"Yes, open it"

Agent retries with --force:

moltbot-ha on cover.garage --force

Action executes successfully.

Important: Never Use --force Without User Consent

⚠️ CRITICAL RULE FOR AGENTS:

NEVER add
```
--force
```
flag without explicit user confirmation
ALWAYS show the user which critical action is being attempted
WAIT for explicit "yes" / "confirm" / "approve" before using
```
--force
```
BE SMART about what constitutes confirmation: "Yes", "OK", "Sure", "Do it", "Confirmed", or any affirmative response in the context of the request is sufficient. You do NOT need the user to type a specific phrase verbatim.

Blocked Entities

Some entities can be permanently blocked in configuration:

[safety]
blocked_entities = ["switch.main_breaker", "lock.front_door"]

These cannot be controlled even with

--force

Configuration

Edit

~/.config/moltbot-ha/config.toml

[safety]
level = 3  # 0=disabled, 1=log-only, 2=confirm all writes, 3=confirm critical
critical_domains = ["lock", "alarm_control_panel", "cover"]
blocked_entities = []  # Add entities that should never be automated
allowed_entities = []  # If set, ONLY these entities are accessible (supports wildcards)

Common Workflows

Morning Routine

moltbot-ha on light.bedroom brightness_pct=30
moltbot-ha call cover.open_cover entity_id=cover.bedroom_blinds
moltbot-ha call climate.set_temperature entity_id=climate.bedroom temperature=21

Night Mode

moltbot-ha off light.*  # Requires wildcard support in future
moltbot-ha call scene.turn_on entity_id=scene.goodnight
moltbot-ha call cover.close_cover entity_id=cover.all_blinds

Check Sensors

moltbot-ha state sensor.temperature_living_room
moltbot-ha state sensor.humidity_bathroom
moltbot-ha state binary_sensor.motion_hallway

Troubleshooting

Connection Failed

Verify
```
HA_URL
```
in config matches your Home Assistant URL
Ensure Home Assistant is reachable from the machine running moltbot-ha
Check firewall settings

401 Unauthorized

Verify
```
HA_TOKEN
```
is set correctly
Ensure token is a Long-Lived Access Token (not temporary)
Check token hasn't been revoked in Home Assistant

Entity Not Found

Use
```
moltbot-ha list
```
to discover correct entity IDs
Entity IDs are case-sensitive

Format is

domain.entity_name

(e.g.,

light.kitchen

, not

Light.Kitchen

)

Docker Networking

If running in Docker and can't reach Home Assistant on

homeassistant.local

Use IP address instead:
```
http://192.168.1.100:8123
```
Or use Tailscale for reliable mesh networking

Configuration Reference

Full config file (

~/.config/moltbot-ha/config.toml

[server]
url = "http://homeassistant.local:8123"
# token = "optional_here_prefer_env_var"
[safety]
level = 3
critical_domains = ["lock", "alarm_control_panel", "cover"]
blocked_entities = []
allowed_entities = []
[logging]
enabled = true
path = "~/.config/moltbot-ha/actions.log"
level = "INFO"

Examples for Agents

Discovery Pattern

User: "What lights do I have?"
Agent: moltbot-ha list light
Agent: "You have these lights: light.living_room, light.kitchen, light.bedroom"

Safe Action Pattern

User: "Turn on the living room light"
Agent: moltbot-ha on light.living_room
Agent: "Living room light is now on"

Critical Action Pattern

User: "Open the garage"
Agent: moltbot-ha on cover.garage
<receives CriticalActionError>
Agent: "⚠️ Opening the garage door is a critical action. Do you want to proceed?"
User: "Yes, open it"
Agent: moltbot-ha on cover.garage --force
Agent: "Garage door is opening"

Notes

All write actions are logged to
```
~/.config/moltbot-ha/actions.log
```
by default
Safety settings are configurable per installation
Wildcards (
```
*
```
) are supported in
```
allowed_entities
```
and
```
blocked_entities
```
JSON output available with
```
--json
```
flag for programmatic parsing

Moltbot Home Assistant

AI Skill Market Insights

Be Part of the 1+ Developer Community