💻CLI Reference›turtles connect›ha

turtles connect ha

Connect Home Assistant to let your Turtles control smart home devices — lights, sensors, climate, switches, and more.

OpenTurtles supports multi-instance connections, so you can control multiple HA servers (e.g. home and office) from a single machine.

turtles connect ha add

Add or update an HA server (interactive wizard)

Usage: turtles connect ha add <NAME>

Arguments:
  <NAME>  Server name (e.g. "home", "office")

Options:
  -h, --help  Print help

Example:

$ turtles connect ha add home

  🏠 Add Home Assistant: home

  HA URL (e.g. http://homeassistant.local:8123): http://homeassistant.local:8123

  To get a token: HA → Profile → Long-Lived Access Tokens → Create Token
  Access Token: eyJ0eXAiOiJKV1QiLCJhbGciOi••••••••

  Testing connection... ✓ (API running.)

  📡 Discovered 47 entities:
     light: 12
     switch: 8
     sensor: 15
     climate: 3
     binary_sensor: 5
     media_player: 2
     automation: 2

  ✓ Home Assistant 'home' connected!
    URL: http://homeassistant.local:8123

  ℹ Test: turtles connect ha test home

Getting a Long-Lived Access Token

  • Open your Home Assistant dashboard
  • Click your profile icon (bottom-left)
  • Scroll to Long-Lived Access Tokens
  • Click Create Token
  • Name it "OpenTurtles" and copy the token

    • turtles connect ha list

    $ turtles connect ha list

  Home Assistant Servers  (2 configured)

  ● home ★ default
    URL: http://homeassistant.local:8123
  ● office
    URL: http://192.168.1.100:8123

    turtles connect ha test

    $ turtles connect ha test home
  ✓ HA server 'home' connected! (API running.)

    turtles connect ha describe

    Inspect all entities available on a server:

    $ turtles connect ha describe home

  📡 home — 47 entities:

    light: 12
    switch: 8
    sensor: 15
    climate: 3
    binary_sensor: 5
    media_player: 2
    automation: 2

    turtles connect ha remove

    $ turtles connect ha remove office
  ✓ Removed HA server 'office'.

    Or use turtles disconnect:

    $ turtles disconnect ha:office
  ✓ Disconnected HA server 'office'.

    Available Tools

    Once connected, each HA server provides 3 tools to your Turtles:

  • ha.getState — Get current state of a specific entity
  • ha.getStates — Get all entity states (with optional domain filter)
  • ha.callService — Call a Home Assistant service (e.g. turn on lights)

    • How it works in practice:

    When you create a Turtle like:

    $ turtles create "turn off all lights when nobody is home"

    The compiler automatically discovers your HA connection and generates code that uses ha.getStates to check presence sensors and ha.callService to control lights — all from your one-sentence description.

    Configuration

    HA configs are stored at ~/.turtles/ha/servers.json:

    {
  "home": {
    "url": "http://homeassistant.local:8123",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOi..."
  }
}

    The default server name is stored at ~/.turtles/ha/default. The first server you add is automatically set as default.

    ← turtles connect skillHealth →