Saltar a contenido

ha CLI

CLI built-in en Home Assistant OS y Home Assistant Supervised que controla updates de Core / Supervisor / OS desde shell. Útil para automatizar pre-update checks, rollbacks parciales y scripts de upgrade disparados por agentes.

Contexto

Para tratar HA "como un problema de software engineering", el ha CLI es la superficie programable de HAOS. Permite que un script (o un agente Claude Code) ejecute updates y rollbacks sin interacción humana en la UI. Es el puente entre el modelo declarativo del repo de configs y el modelo imperativo "update X to version Y".

Contenido

Comandos relevantes para upgrade reliability

# Update del Core HA a la última versión disponible
ha core update

# Update del Supervisor
ha supervisor update

# Update del HAOS
ha os update

# Pin / rollback: forzar versión específica del Core
ha core update --version 2026.4.3

Disponibilidad

  • ✅ HA OS (incluyendo HA Yellow del usuario): disponible nativamente.
  • ✅ HA Supervised (deprecated, ver ../entities/home-assistant-supervised): disponible.
  • ❌ HA Container: el CLI no existe igual. El equivalente operativo es cambiar el tag de la imagen en docker-compose.yml y reiniciar (docker compose pull && docker compose up -d).
  • ❌ HA Core (install method deprecated): no aplica.

Patrones de uso

Rollback core-only (procedimiento documentado)

Ver ../concepts/ha-rollback-procedure opción B.

# guardar versión actual antes del upgrade
ha core info | grep version

# si falla el upgrade y queremos volver:
ha core update --version <previous_version>

Recovery: forzar HAOS desestancado (failure mode documentado)

Cuando la UI deja de ofrecer updates y ha os update responde "already installed" pese a estar en versión obsoleta (caso documentado en ../sources/community-stuck-haos-april-2026):

# verificar versión actual
ha os info

# saltar a una versión intermedia explícita
ha os update --version 17.2   # ejemplo del caso real (gap 10.5 → 17.2)

# tras restart, forzar HA Core a una versión compatible
ha core update --version 2026.4.1

# después, la UI vuelve a ofrecer updates "automáticamente"

Patrón general: cuando el mecanismo automático no encuentra upgrade path, el --version explícito salta la verificación que estaba bloqueando. Es la herramienta de último recurso antes del full restore. Documentado en ../analysis/failure-mode-stuck-haos-update-mechanism.

Script de upgrade controlado

Esqueleto que un agente puede ejecutar dado un repo de configs + checklist:

set -euo pipefail

CURRENT=$(ha core info | awk '/version:/ {print $2}')
TARGET="$1"   # ej. 2026.5.1

# 1. pre-checks
ha core check                # validate config
# (snapshot via API; backup ID guardado para rollback)

# 2. update
ha core update --version "$TARGET"

# 3. smoke test (subset)
# (curl https://ha.local:8123/api/states con filtro)

(NB: este es un patrón sugerido; cuando se ingiera un source con un script público probado, reemplazar.)

Detalles a verificar en docs canónicas

  • ¿ha core check existe como subcomando estable? (Validar contra Settings → Developer Tools → Check Configuration.)
  • Códigos de salida documentados (para CI / agente).
  • Permisos requeridos / autenticación.

Relaciones

Citas / evidencia

Abierto / gaps

  • Documentar autenticación / API token si se llama desde un agente que no corre dentro del Supervisor (caso Container vía REST API).
  • Documentar el output exacto de ha core info / ha supervisor info (para parseo en scripts).
  • Equivalente para HA Container: patrón Docker Compose canónico, con backup del bind mount como prerequisito.