HA CLI를 이용한 재부팅 및 재시작 명령어 완벽 정리

홈 어시스턴트(Home Assistant)를 운영하다 보면 설정 변경 후 재시작이 필요하거나, 업데이트 후 시스템 전체를 재부팅해야 할 때가 생깁니다. 이럴 때 웹 UI보다 빠르게 처리할 수 있는 것이 바로 CLI(명령줄 인터페이스) 입니다.

이 포스팅에서는 ha CLI 명령어를 이용해 Core / Supervisor / Host 각 레이어를 재시작하는 방법을 정리합니다.

ha CLI란?

ha는 Home Assistant OS 및 Supervised 환경에서 제공하는 공식 CLI 도구입니다. SSH 애드온이나 터미널 애드온을 통해 접속한 뒤 사용할 수 있습니다.

ha --help

접속 방법: Home Assistant 웹 UI → 설정 → 애드온 → SSH & Web Terminal 애드온 설치 후 터미널에서 입력합니다.

Home Assistant의 구조 이해

명령어를 이해하려면 HA의 레이어 구조를 먼저 알아야 합니다.

┌─────────────────────────────┐
│        Host (OS 레이어)      │  ← 하드웨어 위에서 동작하는 OS
├─────────────────────────────┤
│     Supervisor (관리자)      │  ← 애드온·Core 등을 관리
├─────────────────────────────┤
│    Core (HA 핵심 엔진)       │  ← 자동화, 엔티티, 연동 처리
└─────────────────────────────┘

재부팅 범위에 따라 영향을 받는 레이어가 달라지므로, 상황에 맞는 명령어를 선택하는 것이 중요합니다.

재부팅 명령어 비교표

1. ha core restart — HA Core만 재시작

명령어

ha core restart

언제 사용하나요?

• configuration.yaml 등 설정 파일을 수정한 뒤 적용할 때
• 자동화나 스크립트가 정상 작동하지 않아 Core만 재시작하고 싶을 때
• 애드온(예: Mosquitto, Node-RED 등)은 건드리지 않고 HA 엔진만 재시작하고 싶을 때

참고 사항

• 애드온은 그대로 유지되며 영향을 받지 않습니다.
• 재시작 중에는 웹 UI 접속이 일시적으로 끊깁니다.
• 가장 빠르고 영향 범위가 작은 재시작 방법입니다.

2. ha supervisor restart — Supervisor 재시작

명령어

ha supervisor restart

언제 사용하나요?

• Supervisor 자체에 오류가 발생했을 때
• 애드온이 비정상 상태로 감지될 때
• Supervisor 업데이트 후 반영이 필요할 때

참고 사항

• Supervisor가 재시작되면 Core도 함께 재시작됩니다.
• 실행 중인 애드온이 잠시 중단될 수 있습니다.
• ha core restart보다 범위가 넓으므로, Core 문제라면 굳이 사용할 필요는 없습니다.

3. ha host reboot — 시스템 전체 재부팅

명령어

ha host reboot

언제 사용하나요?

• Home Assistant OS 업데이트 후 재부팅이 필요할 때
• 하드웨어 연결 장치(예: Z-Wave, Zigbee 동글)가 인식되지 않을 때
• 시스템 전반적으로 불안정한 상태일 때
• 오랫동안 재부팅하지 않아 메모리 누수 등이 의심될 때

참고 사항

• 하드웨어 수준에서 재부팅하므로 가장 확실한 방법입니다.
• 부팅 완료까지 시간이 가장 오래 걸립니다 (장치 사양에 따라 2~5분 이상).
• 모든 애드온과 서비스가 중단되므로 불필요한 경우에는 사용을 자제하세요.

명령어 선택 가이드

설정 파일 수정 후 적용이 필요한가요?
  → ha core restart

Supervisor 관련 오류가 발생했나요?
  → ha supervisor restart

OS 업데이트 또는 하드웨어 문제인가요?
  → ha host reboot

원칙: 가능한 한 영향 범위가 작은 명령어부터 시도하세요.
ha core restart → ha supervisor restart → ha host reboot 순으로 확대하는 것이 좋습니다.

마무리

ha CLI는 웹 UI보다 훨씬 빠르게 작업을 처리할 수 있어, SSH로 접속 가능한 환경이라면 익혀두면 편리합니다. 특히 UI가 응답하지 않는 상황에서도 CLI로는 명령을 내릴 수 있다는 점이 큰 장점입니다.

다음 포스팅에서는 ha CLI의 다른 유용한 명령어들도 정리해보겠습니다.

이 포스팅은 Home Assistant OS / Supervised 환경을 기준으로 작성되었습니다.