pp-home-assistant

Home Assistant — Printing Press CLI

前提条件：CLI をインストールする

このスキルは home-assistant-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールします。

1. Printing Press インストーラーを使用してインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

   npx -y @mvanhorn/printing-press-library install home-assistant --cli-only
   

2. バージョンを確認します：home-assistant-pp-cli --version
3. 報告されたインストール先のディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールしてください（Go 1.26.6 以降が必要です）。インストール先は $GOPATH/bin（デフォルトは $HOME/go/bin）なので、代わりにこのディレクトリを $PATH に追加します。

go install github.com/mvanhorn/printing-press-library/library/devices/home-assistant/cmd/home-assistant-pp-cli@latest

インストール後、--version で「command not found」と表示される場合、ランタイムからバイナリのディレクトリを $PATH 経由で参照できていません。確認に成功するまで、スキルのコマンドを実行しないでください。

hass-cli や ha-mcp の有用な機能を幅広く網羅し、さらにプレビュー／適用／検証モード、日常的なデバッグ、参照先のリント、ヘルス関連の重点項目、世帯内の例外チェックを追加します。同じ型付き Go コマンドツリーを、人、スクリプト、エージェント、MCP クライアントが利用できます。

この CLI を使用する場面

エージェントが Home Assistant の世帯を調査または制御する必要がある場合、ルーティンをデバッグする場合、セルフホスト環境を保守する場合、複数のエンティティや履歴にまたがる質問に回答する場合に、この CLI を使用します。フレンドリー名から推測するのではなく、変更をプレビューして機械可読な形式で確認し、検証する必要がある場合に特に役立ちます。

使用しない場面

次の場合は、この CLI を使用しないでください。

• Home Assistant にブリッジ接続されていない Apple のホームアプリや HomeKit デバイスの制御には使用しないでください。
• Home Assistant の認証を回避したり、プライベートなインスタンスをパブリックインターネットに直接公開したりするために使用しないでください。
• ドライランまたは計画の出力を確認せずに、レジストリの破壊的な操作、復元、再起動、更新のコマンドを実行しないでください。
• 必要なリソースを同期する前に、ローカル限定の複合コマンドを使用しないでください。

独自の機能

これらの機能は、この API のほかのツールでは利用できません。

世帯の安全な操作

• mode run — シーンまたはスクリプトをプレビューして実行し、結果として生じたすべてのエンティティ状態を検証します。

  未検証のシーンやサービス呼び出しを実行するのではなく、エージェントが複数の世帯デバイスを安全に変更する必要がある場合に使用します。

  home-assistant-pp-cli mode run movie-night --agent
  

世帯の状況把握

• house check — 開いている窓、ロック解除されたドア、消し忘れた照明、バッテリー残量の低下、利用できない安全機器をまとめて確認できます。

  複数のエンティティドメインにまたがる、世帯の安全性や快適性に関する緊急の質問に使用します。

  home-assistant-pp-cli house check --agent --select category,entity_id,friendly_name,area,state,severity
  

• house recap — 最近の期間について、世帯内の事実に基づくアクティビティ、ルーティンの失敗、在室状況の変化、開閉状況、利用できなかった時間を確認できます。

  オフラインでも役立つ、簡潔で根拠に基づいた世帯の概要を得るために使用します。

  home-assistant-pp-cli house recap --since 7d --agent
  

ルーティンのインテリジェンス

• routine why — トレース、状態変化、ログブックのエントリ、エラーから、オートメーションまたはスクリプトが失敗した原因を再構成します。

  不透明なトレース全体を出力するのではなく、失敗したルーティンひとつの根拠をエージェントが必要とする場合に使用します。

  home-assistant-pp-cli routine why automation.movie_night --agent
  

• routine lint — 見つからないエンティティ、利用できないサービス、無効化された依存関係、曖昧な名前、古くなったルーティン参照を検出します。

  Home Assistant がルーティンを実行する前に、設定変更やアップグレードの前段階で、確実に予測できる不具合を検出するために使用します。

  home-assistant-pp-cli routine lint --agent
  

• routine impact — あるエンティティまたはルーティンを変更した場合に影響を受ける、すべてのオートメーション、スクリプト、シーン、ヘルパー、サービスの対象を確認できます。

  ほかの世帯内ルーティンが依存している可能性のあるものを、名前変更、無効化、削除する前に使用します。

  home-assistant-pp-cli routine impact light.living_room --agent
  

セルフホスト環境のメンテナンス

• health hotspots — 繰り返し発生する利用不可、古い情報、低バッテリー、切断中のエンティティを、デバイス、部屋、インテグレーション、無線ネットワークのホットスポットに分類します。

  多くのエンティティに症状が見られ、共通の原因が故障したデバイス、インテグレーション、部屋、または無線ネットワークにある可能性がある場合に使用します。

  home-assistant-pp-cli health hotspots --agent
  

• energy standby — 関連する家庭内の状態が非アクティブであることを示す明示的な期間中に、継続して電力を消費するデバイスを検出します。

  家庭のエネルギー履歴を、対処可能な待機時消費電力のリストにまとめる場合に使用します。

  home-assistant-pp-cli energy standby --since 7d --agent
  

コマンドリファレンス

calendars — カレンダーを管理します

• home-assistant-pp-cli calendars list — カレンダーを一覧表示します
• home-assistant-pp-cli calendars list-events — カレンダーのイベントを一覧表示します

components — コンポーネントを管理します

• home-assistant-pp-cli components — 読み込み済みのコンポーネントを一覧表示します

config — 設定を管理します

• home-assistant-pp-cli config get-system-info — Home Assistant の設定とバージョンを取得します
• home-assistant-pp-cli config validate — Home Assistant の設定を検証します

error-log — エラーログを管理します

• home-assistant-pp-cli error-log — 現在のエラーログを取得します

events — イベントを管理します

• home-assistant-pp-cli events fire — イベントを発生させます
• home-assistant-pp-cli events list — イベントの種類を一覧表示します

history — 履歴を管理します

• home-assistant-pp-cli history <timestamp> — 指定した時間範囲のエンティティ履歴を取得します

intent — インテントを管理します

• home-assistant-pp-cli intent — Assist のインテントを処理します

logbook — ログブックを管理します

• home-assistant-pp-cli logbook <timestamp> — 指定した時間範囲のログブックを取得します

services — サービスを管理します

• home-assistant-pp-cli services call — Home Assistant のサービスを呼び出します
• home-assistant-pp-cli services list — サービスドメインとサービスを一覧表示します

states — 状態を管理します

• home-assistant-pp-cli states delete — カスタムエンティティの状態を削除します
• home-assistant-pp-cli states get — エンティティの状態を取得します
• home-assistant-pp-cli states list — 現在のエンティティの状態を一覧表示します
• home-assistant-pp-cli states set — カスタムエンティティの状態を設定します

template — テンプレートを管理します

• home-assistant-pp-cli template — Home Assistant のテンプレートをレンダリングします

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接問い合わせてください。

home-assistant-pp-cli which "<capability in your own words>"

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の候補が見つかったことを示し、終了コード 2 は確信を持てる候補が見つからなかったことを示します。その場合は --help に切り替えるか、より具体的な問い合わせを使用してください。

レシピ

家の状態を確認する

home-assistant-pp-cli house check --agent --select category,entity_id,friendly_name,area,state,severity

家全体の例外レポートを、エージェントが次の対応を判断するために必要なフィールドに絞り込みます。

映画鑑賞の夜をプレビューする

home-assistant-pp-cli mode run movie-night --dry-run --agent

デバイスを変更せずに、家庭のモードを特定し、すべてのアクションを確認します。

失敗したルーティンを説明する

home-assistant-pp-cli routine why automation.movie_night --agent

関連するトレース、状態、ログブック、エラーの証拠をまとめて、1 つのインシデントタイムラインにします。

メンテナンスのホットスポットを確認する

home-assistant-pp-cli health hotspots --agent

繰り返し発生する症状を、対応が必要な可能性が最も高いデバイス、インテグレーション、エリア、無線ネットワークに分類します。

認証の設定

HASS_SERVER に Home Assistant インスタンスの URL を、HASS_TOKEN に Home Assistant プロフィールから作成した長期アクセストークンを設定します。CLI は REST ではベアラー認証情報として、WebSocket 認証ではアクセストークンとしてトークンを送信します。トークンが出力または同期されることはありません。

home-assistant-pp-cli doctor を実行して、設定を確認します。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ処理可能 — stdout に JSON、stderr にエラーを出力します

• フィルター可能 — --select でフィールドを絞り込めます。ドット区切りのパスはネストされた構造をたどり、配列では各要素を順にたどります。出力の多い API でコンテキストを小さく保つうえで重要です：

  home-assistant-pp-cli calendars list --agent --select id,name,status
  

• 事前確認可能 — --dry-run を指定すると、リクエストを送信せずに内容を表示します

• オフラインに対応 — 同期／検索コマンドは、利用可能な場合、ローカル SQLite ストアを使用できます

• 非対話型 — プロンプトは表示せず、すべての入力をフラグで指定します

• 明示的な再試行 — すでに存在する項目の作成を成功として扱う場合に限り --idempotent を使用し、削除対象が存在しない場合を成功として扱う場合に限り --ignore-missing を使用します

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を情報源を示すエンベロープで包みます：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を解析し、ライブデータかローカルデータかを確認するには .meta.source を参照してください。stdout が端末であり、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が指定されていない場合に限り、人間が読みやすい N results (live) の概要が stderr に出力されます。パイプ／エージェントの利用者や、出力形式を明示した実行では、stdout に JSON のみが出力されます。

パスと状態

エージェントは、CLI のパス解決機能をランタイム契約の一部として扱ってください：

• 1 回の呼び出しでパスを指定するには --home <dir> を使用するか、HOME_ASSISTANT_HOME=<dir> を設定して、4 種類すべてのパスを 1 つのルート配下に移動します。

• 特定の種類のパスだけを分ける必要がある場合に限り、種類ごとの環境変数 HOME_ASSISTANT_CONFIG_DIR、HOME_ASSISTANT_DATA_DIR、HOME_ASSISTANT_STATE_DIR、HOME_ASSISTANT_CACHE_DIR を使用します。

• 解決の優先順位は、種類ごとの環境変数、--home、HOME_ASSISTANT_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルトの順です。

• config には config.toml やプロファイルなどの設定が含まれます。data には credentials.toml、data.db、Cookie、認証用サイドカーファイルが含まれます。state には永続化されたクエリ、ジョブ、teach.log が含まれます。cache には再生成可能な HTTP／キャッシュファイルが含まれます。

• 保存されたシークレットは、data ディレクトリ内の credentials.toml に格納されます。既存のレガシーな config.toml のシークレットは互換性のために読み込まれ、最初の認証情報の書き込み時に config.toml から削除されます。

• home-assistant-pp-cli doctor --fail-on warn を実行すると、パスと認証情報の保存場所に関する警告を確認できます。agent-context は、解決済みのディレクトリが必要なエージェント向けに、スキーマ v4 の paths ブロックを公開します。

• MCP では、MCP ホストの設定を通じてパスの移動先を渡します。MCP バイナリは CLI フラグを継承しません：

  {
    "mcpServers": {
      "home-assistant": {
        "command": "home-assistant-pp-mcp",
        "env": {
          "HOME_ASSISTANT_HOME": "/srv/home-assistant"
        }
      }
    }
  }
  

フリートでの優先順位：継承された種類ごとの環境変数は、その種類について明示的に指定された --home より優先されます。フリート全体に適用する設定には HOME_ASSISTANT_HOME または種類ごとの環境変数を使用し、--home は単一の呼び出しにのみ使用してください。環境変数の設定を解除しても、パスの移動は元に戻りません。HOME_ASSISTANT_HOME を解除する前に、ファイルを手動で移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

自動学習

この CLI には、自己記録型の学習ループが組み込まれています。CLI が記録管理を行い、呼び出しのたびに内容がローカルに記録されます。フラグの指定に失敗した後、修正して再試行すると flag_alias 候補が自動的に導出されます。また、プレイブックのないクエリファミリーに対して teach を実行すると、セッションの記録から playbook_candidate が自動的に生成されます。あなたが行うのは判断だけです。まず recall を実行し、表示された候補に基づいて行動し、最終的な回答を teach で記録し、修正を確認した場合は playbook amend を実行します。失敗を手作業で記録する必要はありません。

ステップ 1：探索の前に recall

新しいユーザーの質問について list／search／drill コマンドを実行する前に、次を実行します：

home-assistant-pp-cli recall "<user's question>" --agent

レスポンスエンベロープ：

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "home-assistant-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

ストアが空の場合の早期終了：ストアに学習内容、プレイブック、候補がまだなく（recall で何も見つからず、learnings list と learnings candidates の両方も空の場合）、クエリごとに負荷をかけないよう、このセッションの残りでは recall を省略してください。何かを教えたら、まず recall を実行する手順に戻してください。

ステップ 2：判断ツリー

candidates、playbook、notes、results[0]、警告の順に読み取ります。

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `home-assistant-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook と Notes は、リソースごとの経路とは別のものです。recall の応答には Playbook と Results[] のヒットの両方が含まれることがあります。両方を活用してください。Playbook は実行する手順を示し、リソースのヒットが特定のステップを省略できるようにします。通常は mismatches をスキップし、コールドスタート時の予期しない動作を調査する場合に限り --debug-mismatches を渡してください。

候補の判断に関する詳細：learnings confirm <id> は候補を反映する前に、候補の全ペイロードを出力します。出力されたペイロードが、確認済みの動作と一致することを確認してください。learnings reject <id> は導出シグネチャを tombstone 化するため、同じ候補が再び表示されることはありません。エンベロープには、今すぐ対処する価値がある候補だけが含まれます。home-assistant-pp-cli learnings candidates を実行すると、未処理の候補すべてが表示されます。

グレースフルデグラデーション：learnings confirm が不明なコマンドの場合、古いバイナリを使用しています。候補に関するガイダンスは無視し、残りのプロトコルに従ってください。

ステップ 3：常に warnings を読む

• low_confidence：confidence<2 の行が存在します。スキップディスカバリーに使えるヒットではなく、ヒントとして扱ってください。
• resource_not_in_store：ローカルストアに、学習が参照するリソースがありません。一致検証でエンティティを分類できなかったため、直接取得して再評価してください。
• cross_alias_match（結果ごと）：その行は別のエイリアスで登録されましたが、entity_lookups を通じてライブクエリの正規名と一致しました（例：「USA」での登録が「United States」の recall を満たす場合）。resource_id を信頼してください。
• similar_shape_different_entity:<canonical>（トップレベル）：構造的に一致する行は存在しますが、その正規エンティティはライブクエリのものと異なります。コールドスタートとして扱われます。警告にはヒントとして競合する正規名が含まれますが、その行は Results に昇格されません。
• ambiguous_alias（トップレベル）：単一のクエリエンティティが複数の正規名に解決されました（例：「Cards」→ Arizona Cardinals と St. Louis Cardinals）。リソースを決定する前に、コンテキストから曖昧さを明らかにしてください。
• candidates_present（トップレベル）：エンベロープに candidates セクションが含まれています。ほかのことをする前に、ステップ 2 の候補分岐に従って処理してください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティにはまだ lookup 行がありませんが、同期済みデータから作成できる可能性があります。home-assistant-pp-cli sync を実行して、エンティティルックアップを更新してください。
• トップレベルの no_learnings_for_query_family：テーブルに Jaccard の下限値を超える行がありません。完全なコールドスタートです。

ステップ 4：応答を確定したら必ず teach &

学習は必ず行います。ストアが回答できなかったクエリを解決したら、最終的なリソースのマッピングをバックグラウンドで学習させます。呼び出し回数にしきい値はなく、学習する価値があったかどうかを判断する必要もありません。teach はこのループの要です。Playbook がないファミリーでは Playbook の合成を開始し、同じ参照先を指す異なる表現は 1 つのファミリーにまとめられるため、重複に近い teach によってストアが分断されることはありません。ユーザーに表示する応答を組み立てた後、応答を出力する前に、シェルの & を付けて実行すると、呼び出しはすぐに戻ります。

home-assistant-pp-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功時は何も出力されません。エラーは解決済みの状態ディレクトリにある teach.log にのみ記録されます。最も具体的なリソースを teach してください。ユーザーの質問が広範で、親レコードをたどって具体的な回答を見つけた場合は、親ではなく末端の ID を teach してください。CLI は recall 時にシード済みの entity_lookups を使って異なるエイリアスを解決するため、あるエイリアス（例：「Niners」）での teach は、別のエイリアス（例：「49ers」、「San Francisco」）を使った今後のクエリにも自動的に適用されます。

PII に関するルール：識別子を取り除いた構造的な質問を teach してください。名前、メールアドレス、電話番号、アカウント ID、その他の個人識別子を、teach するクエリやメモに含めないでください。CLI は teach クエリに明らかなメールアドレスや電話番号の形式がないかスキャンして警告しますが、処理をブロックすることはありません。警告に頼らず、teach の前に取り除いてください。

ステップ 5：プレイブック — オプションのフラグ、自動合成

セッションにプレイブックが「ふさわしい」かどうかを判断する必要はありません。プレイブックがないファミリーに対して teach を実行すると、セッションのジャーナルから playbook_candidate が自動合成され、次のセッションで確認または却下されます。明示的なプレイブックフラグを付けるのは、そのまま記録する価値のある手順をすでに把握している場合に限ります。CLI では見つからなかった回避策（気付かれずに破棄されるフラグ、未公開のパラメーター、ページネーションの工夫、ペイロードに関する注意点など）が該当します。統合された一度の呼び出し形式を優先してください。リソースに関する学習内容とプレイブックを、同じ teach 呼び出しで記録します。

# Common case: record both the resource learning AND the playbook in one call.
home-assistant-pp-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
home-assistant-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

プレイブックファイルは steps、entity_slots、expected_tool_calls を含む JSON です。ノートファイルは注意点をそのまま記載した Markdown です。ファイルを扱わない呼び出し元（MCP のみのエージェント）は、同じ内容をインラインで渡します。統合された teach 形式では --playbook-json と --playbook-notes を、teach-playbook では --playbook-json と --notes を使用します。統合された teach 形式では、プレイブックのフラグはオプションです。リソースのみを教える場合は、フラグをすべて省略してください。単独の teach-playbook 形式では、プレイブックとノートのフラグの少なくとも一方を設定する必要があります。両方が空の場合は拒否されます。プレイブックは、構造上のクエリファミリー（エンティティを取り除いたもの）に基づいて管理されます。そのため、あるエンティティ形状のクエリから学習したレシピは、同じ形状を持つほかのすべてのクエリに適用されます。呼び出し時には slots_resolved が、実際のクエリの正規形を割り当てます。

今後の呼び出しでプレイブックが見つかった場合は、それを確かな情報源として扱ってください。slots_resolved による置換を適用して手順を再実行し、すでに手順書に記載されている探索は省略して、どの手順よりも先に notes を読んでください。

ステップ 6：デバッグ応答で修正点を特定した場合は、playbook amend & を実行する

デバッグプロトコルへの応答で、ノートやプレイブックに反映すべき具体的な修正点（回避策、未公開のエンドポイント形式、古いフィールド名、確認されたスキーマの変化、空のペイロードへのフォールバックなど）を特定した場合は、ユーザー向けの応答を出す前に playbook amend を実行してください。teach と同様に、実行後の完了を待たずに進めます。

home-assistant-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

修正する価値があるもの：このセッションで実際に確認した動作で、将来の自分が知っていると役立つものです。修正する価値がある例：

• フラグを気付かれずに破棄したり、順序を誤って処理したりする CLI の仕様に対する回避策。
• 未公開のエンドポイント形式（レスポンスが {meta, results} でラップされている、ペイロードがドキュメントの説明よりもさらに 2 階層深いなど）。
• 確認されたスキーマの変化（フィールド名の変更、シーズン間でのインデックスのずれ、API が返すカテゴリラベルの小文字化など）。

ノートに記載しないもの：

• ユーザーの質問に対する、年やエンティティに固有の回答。これは応答であり、学習内容ではありません。
• プレイブックが実行時にすでに取得するチーム、選手、行ごとのデータ。
• 既存のノートの内容を言い換えた記述。

amend コマンドは、ファミリーの既存のノートにタイムスタンプ付きのマーカー（[amend YYYY-MM-DDTHH:MMZ]: <text>）を追記します。複数の amend は蓄積され、監査履歴を確認できます。ファミリーにプレイブックがまだ存在しない場合、amend はノートのみのプレイブックを作成するため、コールドスタート時の修正も反映されます。

amend ノートにおける PII の取り扱い

将来の Printing Press のバージョンで、playbook amend のノートが共有知識として上流に提供される可能性があります。遡及的な削除を行わずに上流への提供を続けられるよう、ユーザーを特定できる情報を含めないでください。

• 含めてはいけないもの：ユーザーのファイルシステム上のパス、個人用の API キーやトークン、ユーザーのメールアドレス、ユーザーの GitHub ハンドル、単一ユーザーに紐付いた特定のクエリ履歴。
• 含めてもよいもの：エンドポイントの形式、未公開のフィールド名、API の注意点、確認されたスキーマの変化、CLI の仕様に対する回避策、汎用的なページネーションや再試行の方法。

修正点がユーザー固有のコンテキストでのみ意味を持つ場合は、プレイブックの amend ではなく、個人用のノートに記録してください。

ループの測定

home-assistant-pp-cli learnings stats は、ローカルの learn_events テーブルから、再呼び出しのヒット率、教示から再利用への移行率、プレイブックの解決率、候補の承認／却下数を報告します。分母がない場合、率は null になります。データはすべてこのマシン内にとどまります。この CLI でループが効果を上げているか確認するために使ってください。

学習の無効化

• 1つのコマンドで --no-learn を指定すると、recall と teach の書き込み処理の両方が停止します。蓄積された学習内容の影響を受けてはならない、決定論的なエージェントフローやテストで使用してください。
• 環境変数に HOME_ASSISTANT_NO_LEARN=true を設定すると、パイプライン全体が無効になります。

エージェントのフィードバック

この CLI で気になる点に気づいたら（あなた自身でもエージェントでも）、記録してください。

home-assistant-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
home-assistant-pp-cli feedback --stdin < notes.txt
home-assistant-pp-cli feedback list --json --limit 10

エントリーは、解決済みのデータディレクトリ内の feedback.jsonl にローカル保存されます。HOME_ASSISTANT_FEEDBACK_ENDPOINT が設定され、かつ --send が渡された場合、または HOME_ASSISTANT_FEEDBACK_AUTO_SEND=true が設定された場合を除き、POST されることはありません。デフォルトの動作はローカル保存のみです。

バグ報告ではなく、予想外だったことを書いてください。短く、具体的に、1行で。それが積み重なっていく部分です。

出力の送信先

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて、または標準出力の代わりに、指定した送信先に出力されます。そのため、エージェントはコマンド結果を手動でパイプ処理せずに送信先へ振り分けられます。対応している送信先は3種類です。

送信先	動作
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してからリネームします）
webhook:<url>	出力本文を URL に POST します（--compact を指定した場合は application/json または application/x-ndjson）

不明なスキームは、対応している送信先を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードが返され、URL と HTTP ステータスが標準エラー出力に記録されます。

名前付きプロファイル

プロファイルは、保存したフラグ値のセットです。実行ごとに異なる入力を与えながら、スケジュール実行または定期実行されるエージェントで同じフラグを再利用する場合に使います。

home-assistant-pp-cli profile save briefing --json
home-assistant-pp-cli --profile briefing calendars list
home-assistant-pp-cli profile list --json
home-assistant-pp-cli profile show briefing
home-assistant-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルトより優先されます。agent-context は、実行時に情報を調べるエージェントがプロファイルを検出できるよう、available_profiles の下に利用可能なすべてのプロファイルを一覧表示します。

終了コード

コード	意味
0	成功
2	使用方法エラー（引数が不正）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → home-assistant-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照します
3. その他 → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします。

   go install github.com/mvanhorn/printing-press-library/library/devices/home-assistant/cmd/home-assistant-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add home-assistant-pp-mcp -- home-assistant-pp-mcp
   

3. 確認します：claude mcp list

直接使用

1. インストールされているか確認します：which home-assistant-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の独自機能とコマンドリファレンスから選びます。
3. --agent フラグを付けて実行します。

   home-assistant-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：home-assistant-pp-cli <command> --help。