---
name: ha-ssh
description: This skill should be used when working with a Home Assistant instance over SSH — for example when the user asks to "check HA status", "view HA logs", "restart Home Assistant", "check the HA config", "ssh into HA", "deploy to HA", "manage automations", "check entity state", or wants to run `ha` CLI commands or manage the config at homeassistant.local. Use this skill whenever the user is doing anything that involves inspecting, modifying, or operating the Home Assistant instance.
version: 1.0.0
---

# Home Assistant SSH Operations

Provides access to a Home Assistant OS (HAOS) instance running on a Raspberry Pi 4 at `homeassistant.local`.

## Connection

```bash
ssh root@homeassistant.local
```

Key-based auth is already configured. Use `ssh -o ConnectTimeout=5` for quick connectivity checks.

## Environment Constraints

The SSH add-on runs an Alpine-based shell with these constraints:
- No `apt`/`dpkg` — package management via `apk` only (within the container)
- No `rsync` — file transfers use `tar` piped over SSH
- The `ha` CLI is the primary interface for HA operations
- HA config lives at `/config/` on the Pi

## HA CLI Reference

```bash
# Core operations
ha core info           # Version, status, IP
ha core restart        # Restart HA core
ha core check          # Validate config (do this before restart)
ha core logs           # View recent logs
ha core logs --follow  # Tail logs

# Backups
ha backups new --name "$(date +%Y%m%d-%H%M)"
ha backups list

# Add-ons
ha addons list
ha addons logs <slug>
ha addons restart <slug>

# Supervisor / system
ha supervisor info
ha os info
```

## Config Management

The local repo at `~/src/ha-ops/` mirrors `/config/` on the Pi.

```bash
# Pull from Pi → local
~/src/ha-ops/scripts/pull.sh

# Push local → Pi (runs ha core check after)
~/src/ha-ops/scripts/deploy.sh

# Validate without deploying
ssh root@homeassistant.local 'ha core check'
```

## Common Tasks

**Check HA version and update availability:**
```bash
ssh root@homeassistant.local 'ha core info'
```

**Inspect a config file:**
```bash
ssh root@homeassistant.local 'cat /config/configuration.yaml'
```

**Edit config inline (for small changes):**
```bash
ssh root@homeassistant.local 'cat > /config/automations.yaml' << 'EOF'
- id: ...
EOF
```

**Check entity state via REST API:**
```bash
# Requires a long-lived access token stored in secrets.yaml or env
curl -s http://homeassistant.local:8123/api/states/<entity_id> \
  -H "Authorization: Bearer <token>"
```

**Check InfluxDB add-on:**
The InfluxDB add-on is available at `a0d7b954-influxdb:8086` from within HA.

## Integrations in This Instance

- **Lutron Caseta** — smart lighting (certs in `/config/`, private key gitignored)
- **Bambu Lab** — 3D printer monitoring (HACS component)
- **HACS** — Home Assistant Community Store
- **InfluxDB** — metrics add-on
- **Zigbee** — device network (database gitignored)

## Secrets

`/config/secrets.yaml` holds all secrets; reference them in YAML as `!secret <key>`. Never echo or log secret values. The Lutron private key (`lutron_caseta-*-key.pem`) is also gitignored.

## Safe Operation Checklist

Before restarting HA core:
1. Run `ha core check` to validate config
2. Optionally create a backup: `ha backups new`
3. Then restart: `ha core restart`
4. Monitor: `ha core logs --follow`