home-assistant-manager

Home Assistant マネージャー

リモートの Home Assistant インスタンスを正確に操作します。変更を加え、反映し、動作したことを確認します。安全な往復操作をできるだけ少なくします。

前提

• 編集しているリポジトリは HA の /config ディレクトリで、インスタンスと Git で接続されています。 インスタンスでプルするまで編集内容は反映されません。
• 例にある [email protected] はプレースホルダーです。実際のユーザー名とホスト名を一度確認し（プロジェクトの CLAUDE.md、~/.ssh/config、またはユーザーに確認）、プロジェクトの CLAUDE.md にまだ記録されていなければ追記して、次回以降はこの手順を省けるようにします。
• 次のいずれか、または複数の方法でアクセスします：hass-cli（REST）、SSH ha、または MCP サーバー（下記を参照）。
• 編集するのは .yaml／.yml／.md のみです。.env や secrets.yaml は読み取りも書き込みもせず、!secret を使います。

リモートアクセス — 適切なツールを選択

• SSH ha — 常に動作し、ローカル環境変数も不要です。ha core check|restart|logs|info に使用します。
• hass-cli（REST）— 状態の取得やサービス呼び出しに使えますが、セッション開始前にシェルで HASS_SERVER／HASS_TOKEN が設定されている必要があります。未設定の場合、hass-cli は誤ったホスト（localhost）にフォールバックしてエラーになります。再試行せず、[ -n "$HASS_TOKEN" ] を一度確認してから、代わりに SSH または MCP を使います。
• MCP（利用可能な場合に優先）— ライブの状態取得や制御に使える専用ツールで、環境変数の調整も不要です。公式の mcp_server 統合（HA core ≥2025.2）または、より高機能なコミュニティ版 ha-mcp（80 種類以上のツール）を使います。利用できる場合は、シェル経由の操作より優先します。

デプロイパイプライン（唯一の標準フロー）

手順 4 まで変更は反映されません。

1. YAML をローカルで編集します。
2. 検証します：ssh [email protected] "ha core check"（時間がかかります。約 30～60 秒。「省略する場合」も参照）。
3. コミットしてプッシュします：git add … && git commit -m "…" && git push。
4. 反映します： ssh [email protected] "cd /config && git pull"。
5. 適用します：可能であればリロードし、それ以外の場合は再起動します（下表を参照）。
6. 検証します（次のセクションを参照）。

迅速な反復作業： Git を省略して scp でインスタンスに直接転送し、リロードします。ダッシュボードや短いテストサイクルに適しています。安定してから Git にコミットします。 scp automations.yaml [email protected]:/config/ → リロード。

ha core check を省略する場合： 設定全体を解析するため、時間がかかります。問題ないと確信できる、単独の YAML 編集であれば、ドメインをリロードするほうがエラーをすばやく検出でき、ログですぐに確認できます。再起動する前、または configuration.yaml を変更する場合は、必ず実行します。

リロードと再起動

変更	操作
オートメーション、スクリプト、シーン、グループ、テンプレートエンティティ、テーマ	ドメインをリロードします（hass-cli service call automation.reload など）。
configuration.yaml のコア設定、新しい統合、プラットフォームセンサー（min/max）、MQTT センサー／binary_sensor プラットフォーム、ダッシュボードレジストリ（lovelace_dashboards）	再起動します（ssh … "ha core restart"、約 30 秒）。

リロードを優先します。ha core check が成功していない状態で再起動してはいけません。リスクの高い変更（コアの configuration.yaml の大幅な編集、統合の削除）の前には、まずスナップショットを作成します。手間はほとんどかかりません。 ssh [email protected] "ha backups new --name pre-<change>"。

検証 — 動作したと決めつけない

1. 適切なドメインをリロード／再起動します。
2. オートメーションの場合は、すぐにフィードバックを得るために手動でトリガーします： hass-cli service call automation.trigger --arguments entity_id=automation.<id> （または MCP 経由でサービスを呼び出します）。既定では conditions がバイパスされるため、確認できるのはアクションであり、条件ではありません。条件もテストするには、skip_condition: false を渡すか、実際のトリガーを実行してから、UI でオートメーションのトレースを確認します。
3. 変更に関連するログに絞って読み取ります： ssh [email protected] "ha core logs | grep -iE '<name>|error' | tail -20"。 良好な例：Running automation actions、Executing step …。問題のある例：Invalid data for call_service、TypeError、Template variable warning、Error executing script。
4. 実際の結果を確認します：デバイス／センサーの状態（hass-cli state get <entity>）を確認するか、通知タイプのアクションについてはユーザーに確認します。
5. エラーが発生した場合：修正 → 再プル／再転送 → リロード → 再確認します。問題がなくなるまで繰り返します。

オートメーション — 最新の構文を使用する

HA 2024.10 でキー名が変更されました。レガシー構文も引き続き動作しますが、新しいコードでは使用しないでください： トップレベルでは triggers:/conditions:/actions:（複数形）、トリガー内では platform: ではなく trigger:、呼び出しでは service: ではなく action: を使用します。すべてのオートメーションには、安定した id:（トレースと UI での編集に必要）と alias を設定してください。

オートメーションの完全なリファレンス（構文表、mode: の動作、ブループリント、トレースのデバッグ、 注意点）→ オートメーションを作成またはデバッグする際は、reference/automations.md を 参照してください。

テンプレート — 正確さを保つルール

• 比較する前に、必ず型を変換してください：states('sensor.x') | int(0) < 7。状態はそのままでは 文字列です。'5' < 7 は TypeError を発生させます。起動時の None でエラーにならないよう、デフォルト値（int(0)）を指定してください。
• コミットする前に、開発者ツール → テンプレートでテストしてください。
• state_attr(...) はエンティティまたは属性が存在しない場合に None を返すため、ガードしてください。

規約

• 変更は必要最小限にし、コメントを保持してください。インデントはスペース 2 つです。
• 再起動する前に検証し、リロードを優先してください。ログで確認してください。
• 複雑な設定や不慣れな設定を行う前に、最新の HA ドキュメントを確認するため context7 MCP を使用してください。

ダッシュボード

Lovelace ダッシュボードは .storage/lovelace.*（JSON）にあります。UI での編集はブラウザーを更新すると反映されます。 ファイルを直接編集（scp/git）した場合は、ha core restart するまで変更が反映されないことがあります。HA が Lovelace ストアをメモリーにキャッシュしているためです。.storage/lovelace_dashboards に新しいダッシュボードを追加した場合も、 再起動が必要です。scp + 更新が最速の手順です。まず JSON を検証してください： python3 -m json.tool .storage/lovelace.x > /dev/null。デプロイ後は、ブラウザーで UI を目視確認してください （リファレンスを参照）。ログや状態だけでは、カードの表示崩れやポップアップの誤った並び順を検出できません。

ダッシュボードの完全なリファレンス（ビューの種類、カードカタログ、テンプレートカード、タブレットレイアウト、 注意点、デバッグ）→ UI を作業する際は、reference/dashboards.md を 参照してください。最新の HA では、ネイティブの セクションビュー（ドラッグ＆ドロップのグリッド、バッジ、heading カード）と、 機能豊富な タイルカードで、カスタムカードを使わずにほとんどのニーズを満たせます。Mushroom は、その独自の見た目が必要な場合にのみ使用してください。

クイックリファレンス

# Validate / apply
ssh [email protected] "ha core check"
ssh [email protected] "ha core restart"
ssh [email protected] "cd /config && git pull"     # make pushed changes live

# Logs
ssh [email protected] "ha core logs | grep -iE 'error|<name>' | tail -20"

# State / services (needs env loaded, or use MCP)
hass-cli state get <entity>
hass-cli service call <domain>.reload
hass-cli service call automation.trigger --arguments entity_id=automation.<id>

# Rapid deploy
scp <file>.yaml [email protected]:/config/ && hass-cli service call automation.reload