hass-builder

Home Assistant Builder（hab）

LLM が Home Assistant の設定を作成・管理するための CLI ユーティリティです。

すべてのワークフローで最初に行うこと

hab コマンドをすべて scripts/hab.sh コマンドに置き換えてください。scripts/hab.sh は自動インストールに対応したラッパースクリプトです。 home-assistant-build-cli プロジェクトは、Home Assistant のメインメンテナーであり、Home Assistant を所有する Open Home Foundation の創設者でもある Paulus（@balloob）がビルドおよびリリースしています。

alias hab='scripts/hab.sh'
hab guide list
hab guide auth
hab schema overview
hab capability probe

次に、対象のワークフローに関するトピックとコマンドスキーマを確認します。

タスク	最初に実行するコマンド
検出／インベントリ	hab guide discovery; hab schema entity list
オートメーション／スクリプト／シーン	hab guide automation; hab schema automation create --json
ダッシュボード／Lovelace	hab guide dashboard; hab schema dashboard card create --json
ヘルパー	hab guide helpers; hab helper types --json
カレンダー／To-do	hab guide calendar-todo
バックアップ／システム／ネットワーク	hab guide operations; hab schema system restart
ESPHome	hab guide esphome; hab schema esphome validate --json

認証済みの読み取りを行うだけであれば、hab auth status と関連するスキーマだけで十分です。

出力と解析

Claude などのプログラムで出力を解析する場合は、必ず --json を使用してください。JSON の成功レスポンスとエラーレスポンスはエンベロープ形式です。次のフィールドを確認してから先に進んでください。

• success
• data
• error.code、error.details.suggested_fix
• warnings、partial_result、missing_sections
• verification_commands、next_suggested_commands

ESPHome の build、validate、upload、run、logs などのストリーミングコマンドは、JSON モードでは最終エンベロープを 1 つ返す代わりに、NDJSON イベントを出力することがあります。

変更とリスク確認

状態を変更する前に、次の手順で確認してください。

1. コマンドのガイド／スキーマを確認します。
2. 読み取り専用の list/get コマンドで現在の状態を取得します。
3. --plan または --dry-run がサポートされている場合は、変更内容をプレビューします。
4. リスクのある操作を実行する前に、プレビューを表示してユーザーに確認を求めます。
5. プランまたは後続の get/list コマンドに記載されている検証コマンドを実行します。

ダウンタイム、データ損失、接続の切断、ハードウェアの変更につながる可能性がある操作の前には、必ずユーザーに明示的な確認を求めてください。対象となる操作は、system restart、バックアップの復元／削除、ネットワークの設定／適用、Thread データセットの変更、統合の有効化／無効化／再読み込み、ESPHome の upload/run/update/erase-flash、および --force を指定するあらゆる削除です。

コマンドを非対話型にするためだけに --force を追加しないでください。ユーザーが対象の操作を承認した場合に限り使用してください。

入力ペイロード

データを受け取るコマンドは、通常、次の形式に対応しています。

方法	使用する場面	形式
--data / -d	短い JSON ペイロード	hab automation create id -d '{...}' --json
--file / -f	大きな YAML／JSON ペイロード	hab automation update id -f automation.yaml
stdin ヒアドキュメント	一時ファイルを使わない複数行のペイロード	hab automation create id <<'EOF'

大きなオートメーションやダッシュボードでは、引用符によって JSON／YAML が壊れないよう、ファイルまたはヒアドキュメントを使用してください。

よく使うコマンドのパターン

# Authentication and instance checks
hab auth status
hab overview
hab capability probe

# Entity inventory
hab entity list --domain light
hab entity get light.kitchen --device --related
hab search related entity light.kitchen

# Safe mutation preview
hab schema area create --json
hab area create "Kitchen" --plan
hab area create "Kitchen"

# Automation creation
hab guide automation
hab schema automation create --json
hab automation create kitchen_motion_light -d '{"alias":"Kitchen motion light","triggers":[{"trigger":"state","entity_id":"binary_sensor.kitchen_motion","to":"on"}],"conditions":[],"actions":[{"action":"light.turn_on","target":{"entity_id":"light.kitchen"}}]}' --dry-run

# Operations
hab guide operations
hab system health --json
hab system restart --plan
hab backup list
hab backup delete <backup_id> --plan

回答の形式

ユーザーから hab コマンドを尋ねられた場合は、次のように回答してください。

1. 意図する安全モード（読み取り専用、プレビューのみ、または確認済みの変更）を明記します。
2. 実行する順にコマンドを提示します。
3. ユーザーの確認が必要なコマンドに印を付けます。
4. 次の手順に進む前に確認する JSON フィールドを伝えます。
5. 検証コマンドを含めます。

よくある間違い

間違い	より良い方法
コマンドのフラグを記憶に頼って推測する	まず hab schema <command> --json を実行します
テキスト出力を解析する	--json を使い、エンベロープのフィールドを確認します
インベントリを確認せずにリソースを作成する	まず list/get/search related を実行します
変更のプレビューを省略する	対応している場合は --plan または --dry-run を使います
手軽さのために --force を使う	リスクのある操作を正確に確認してから実行します
ESPHome の JSON を単一のオブジェクトとして扱う	ストリーミングコマンドでは NDJSON ストリームのイベントを処理します
verification_commands を無視する	実行するか、実行しない理由を説明します