{"skill":{"slug":"moltbot-ha","displayName":"Moltbot Home Assistant","summary":"Control Home Assistant smart home devices, lights, scenes, and automations via moltbot-ha CLI with configurable safety confirmations.","description":"---\nname: moltbot-ha\ndescription: Control Home Assistant smart home devices, lights, scenes, and automations via moltbot-ha CLI with configurable safety confirmations.\nhomepage: https://github.com/iamvaleriofantozzi/moltbot-ha\nmetadata: {\"moltbot\":{\"emoji\":\"🏠\",\"requires\":{\"bins\":[\"moltbot-ha\"],\"env\":[\"HA_TOKEN\"]},\"primaryEnv\":\"HA_TOKEN\",\"install\":[{\"id\":\"uv\",\"kind\":\"uv\",\"package\":\"moltbot-ha\",\"bins\":[\"moltbot-ha\"],\"label\":\"Install moltbot-ha (uv tool)\"}]}}\n---\n\n# Home Assistant Control\n\nControl your smart home via Home Assistant API using the `moltbot-ha` CLI tool.\n\n## Setup\n\n### 1. Install moltbot-ha\n```bash\nuv tool install moltbot-ha\n```\n\n### 2. Initialize Configuration\n```bash\nmoltbot-ha config init\n```\n\nThe setup will interactively ask for:\n- Home Assistant URL (e.g., `http://192.168.1.100:8123`)\n- Token storage preference (environment variable recommended)\n\n### 3. Set Environment Variable\nSet your Home Assistant long-lived access token:\n```bash\nexport HA_TOKEN=\"your_token_here\"\n```\n\nTo create a token:\n1. Open Home Assistant → Profile (bottom left)\n2. Scroll to \"Long-Lived Access Tokens\"\n3. Click \"Create Token\"\n4. Copy the token and set as `HA_TOKEN` environment variable\n\n### 4. Test Connection\n```bash\nmoltbot-ha test\n```\n\n## Discovery Commands\n\n### List All Entities\n```bash\nmoltbot-ha list\n```\n\n### List by Domain\n```bash\nmoltbot-ha list light\nmoltbot-ha list switch\nmoltbot-ha list cover\n```\n\n### Get Entity State\n```bash\nmoltbot-ha state light.kitchen\nmoltbot-ha state sensor.temperature_living_room\n```\n\n## Action Commands\n\n### Turn On/Off\n```bash\n# Turn on\nmoltbot-ha on light.living_room\nmoltbot-ha on switch.coffee_maker\n\n# Turn off\nmoltbot-ha off light.bedroom\nmoltbot-ha off switch.fan\n\n# Toggle\nmoltbot-ha toggle light.hallway\n```\n\n### Set Attributes\n```bash\n# Set brightness (percentage)\nmoltbot-ha set light.bedroom brightness_pct=50\n\n# Set color temperature\nmoltbot-ha set light.office color_temp=300\n\n# Multiple attributes\nmoltbot-ha set light.kitchen brightness_pct=80 color_temp=350\n```\n\n### Call Services\n```bash\n# Activate a scene\nmoltbot-ha call scene.turn_on entity_id=scene.movie_time\n\n# Set thermostat temperature\nmoltbot-ha call climate.set_temperature entity_id=climate.living_room temperature=21\n\n# Close cover (blinds, garage)\nmoltbot-ha call cover.close_cover entity_id=cover.garage\n```\n\n### Generic Service Call\n```bash\n# With parameters\nmoltbot-ha call automation.trigger entity_id=automation.morning_routine\n\n# With JSON data\nmoltbot-ha call script.turn_on --json '{\"entity_id\": \"script.bedtime\", \"variables\": {\"brightness\": 10}}'\n```\n\n## Safety & Confirmations\n\nmoltbot-ha implements a **3-level safety system** to prevent accidental actions:\n\n### Safety Level 3 (Default - Recommended)\n\nCritical operations require explicit confirmation:\n- **lock.***: Door locks\n- **alarm_control_panel.***: Security alarms\n- **cover.***: Garage doors, blinds\n\n### How Confirmation Works\n\n1. **Attempt critical action:**\n```bash\nmoltbot-ha on cover.garage\n```\n\n2. **Tool returns error:**\n```\n⚠️  CRITICAL ACTION REQUIRES CONFIRMATION\n\nAction: turn_on on cover.garage\n\nThis is a critical operation that requires explicit user approval.\nAsk the user to confirm, then retry with --force flag.\n\nExample: moltbot-ha on cover.garage --force\n```\n\n3. **Agent sees this error and asks you:**\n> \"Opening the garage door is a critical action. Do you want to proceed?\"\n\n4. **You confirm:**\n> \"Yes, open it\"\n\n5. **Agent retries with --force:**\n```bash\nmoltbot-ha on cover.garage --force\n```\n\n6. **Action executes successfully.**\n\n### Important: Never Use --force Without User Consent\n\n**⚠️ CRITICAL RULE FOR AGENTS:**\n\n- **NEVER** add `--force` flag without explicit user confirmation\n- **ALWAYS** show the user which critical action is being attempted\n- **WAIT** for explicit \"yes\" / \"confirm\" / \"approve\" before using `--force`\n- **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.\n\n### Blocked Entities\n\nSome entities can be permanently blocked in configuration:\n```toml\n[safety]\nblocked_entities = [\"switch.main_breaker\", \"lock.front_door\"]\n```\n\nThese **cannot** be controlled even with `--force`.\n\n### Configuration\n\nEdit `~/.config/moltbot-ha/config.toml`:\n\n```toml\n[safety]\nlevel = 3  # 0=disabled, 1=log-only, 2=confirm all writes, 3=confirm critical\n\ncritical_domains = [\"lock\", \"alarm_control_panel\", \"cover\"]\n\nblocked_entities = []  # Add entities that should never be automated\n\nallowed_entities = []  # If set, ONLY these entities are accessible (supports wildcards)\n```\n\n## Common Workflows\n\n### Morning Routine\n```bash\nmoltbot-ha on light.bedroom brightness_pct=30\nmoltbot-ha call cover.open_cover entity_id=cover.bedroom_blinds\nmoltbot-ha call climate.set_temperature entity_id=climate.bedroom temperature=21\n```\n\n### Night Mode\n```bash\nmoltbot-ha off light.*  # Requires wildcard support in future\nmoltbot-ha call scene.turn_on entity_id=scene.goodnight\nmoltbot-ha call cover.close_cover entity_id=cover.all_blinds\n```\n\n### Check Sensors\n```bash\nmoltbot-ha state sensor.temperature_living_room\nmoltbot-ha state sensor.humidity_bathroom\nmoltbot-ha state binary_sensor.motion_hallway\n```\n\n## Troubleshooting\n\n### Connection Failed\n- Verify `HA_URL` in config matches your Home Assistant URL\n- Ensure Home Assistant is reachable from the machine running moltbot-ha\n- Check firewall settings\n\n### 401 Unauthorized\n- Verify `HA_TOKEN` is set correctly\n- Ensure token is a **Long-Lived Access Token** (not temporary)\n- Check token hasn't been revoked in Home Assistant\n\n### Entity Not Found\n- Use `moltbot-ha list` to discover correct entity IDs\n- Entity IDs are case-sensitive\n- Format is `domain.entity_name` (e.g., `light.kitchen`, not `Light.Kitchen`)\n\n### Docker Networking\nIf running in Docker and can't reach Home Assistant on `homeassistant.local`:\n- Use IP address instead: `http://192.168.1.100:8123`\n- Or use Tailscale for reliable mesh networking\n\n## Configuration Reference\n\nFull config file (`~/.config/moltbot-ha/config.toml`):\n\n```toml\n[server]\nurl = \"http://homeassistant.local:8123\"\n# token = \"optional_here_prefer_env_var\"\n\n[safety]\nlevel = 3\ncritical_domains = [\"lock\", \"alarm_control_panel\", \"cover\"]\nblocked_entities = []\nallowed_entities = []\n\n[logging]\nenabled = true\npath = \"~/.config/moltbot-ha/actions.log\"\nlevel = \"INFO\"\n```\n\n## Examples for Agents\n\n### Discovery Pattern\n```\nUser: \"What lights do I have?\"\nAgent: moltbot-ha list light\nAgent: \"You have these lights: light.living_room, light.kitchen, light.bedroom\"\n```\n\n### Safe Action Pattern\n```\nUser: \"Turn on the living room light\"\nAgent: moltbot-ha on light.living_room\nAgent: \"Living room light is now on\"\n```\n\n### Critical Action Pattern\n```\nUser: \"Open the garage\"\nAgent: moltbot-ha on cover.garage\n<receives CriticalActionError>\nAgent: \"⚠️ Opening the garage door is a critical action. Do you want to proceed?\"\nUser: \"Yes, open it\"\nAgent: moltbot-ha on cover.garage --force\nAgent: \"Garage door is opening\"\n```\n\n## Notes\n\n- All write actions are logged to `~/.config/moltbot-ha/actions.log` by default\n- Safety settings are configurable per installation\n- Wildcards (`*`) are supported in `allowed_entities` and `blocked_entities`\n- JSON output available with `--json` flag for programmatic parsing\n","tags":{"latest":"0.1.1"},"stats":{"comments":0,"downloads":2626,"installsAllTime":4,"installsCurrent":4,"stars":3,"versions":1},"createdAt":1770056090474,"updatedAt":1778485994101},"latestVersion":{"version":"0.1.1","createdAt":1770056090474,"changelog":"Interactive setup wizard with URL and token prompts. Control Home Assistant via CLI with safety features.","license":null},"metadata":null,"owner":{"handle":"iamvaleriofantozzi","userId":"s172s1gybns5d3ck0rec6ya1td884vve","displayName":"iamvaleriofantozzi","image":"https://avatars.githubusercontent.com/u/252470287?v=4"},"moderation":null}