pp-beehiiv

Beehiiv — Printing Press CLI

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

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

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

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

2. 確認します：beehiiv-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/marketing/beehiiv/cmd/beehiiv-pp-cli@latest

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

Beehiiv-pp-cli は、パブリケーション、購読者、セグメント、投稿、ポッドキャストなどを SQLite にミラーリングします。インサイトコマンドでは、API 呼び出しなしで流入元のアトリビューション、解約の流入元、配信時間のパフォーマンス、パブリケーション間の比較を計算できます。ポッドキャスト、エクスポート、無料アクセスなど、2026-09 に追加された機能を含む v2 の全機能が、ドライランとエージェント出力に対応した型付きコマンドとして提供されます。

この CLI を使用する場面

オフラインでのオーディエンス分析、大量の購読者操作、スクリプト作成、CI パイプラインには、この CLI を使用してください。選択／コンパクト／静音モードを備えたエージェント向け JSON 出力と、API 呼び出しなしで成長に関する疑問に答えられるローカルストアが必要な場合にも適しています。

使用しない場面

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

• beehiv のドキュメント検索には使用しないでください。公式ドキュメント MCP（developers.beehiiv.com/_mcp/server）を使用してください。
• OAuth アプリの認可フローには使用しないでください。これは API キーを使用するクライアントです。
• scheduled_at を指定せずにステータスが confirmed の投稿を作成すると、即時に公開（送信）されます。まず --dry-run を使ってリクエストを確認してください。

独自の機能

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

ローカルストアから成長に関する答えを取得

• insights subscriber-sources — 新規購読者の流入元（UTM、チャネル、参照元サイト）を、1 回の呼び出しでまとめて確認できます。

  成長に関する疑問で、購読者リスト全体を API 経由でページングせずに流入元のアトリビューションを確認したい場合に使用します。

  beehiiv-pp-cli insights subscriber-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20 --agent
  

• insights post-performance — 最近の配信について、ステータス、タイミング、詳細な統計をコンパクトな表でまとめて確認できます。

  配信後に、投稿ごとの API 呼び出しを消費せずにパフォーマンスを確認したい場合に使用します。

  beehiiv-pp-cli insights post-performance pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 10 --agent
  

• insights referral-health — 紹介プログラムの設定と、実際に紹介コードを持つ購読者数を確認できます。

  紹介の仕組みを調整する際に、設定と実際の利用範囲を比較したい場合に使用します。

  beehiiv-pp-cli insights referral-health pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent
  

• insights subscriber-lookup — メールアドレスまたは購読 ID で購読者を検索し、コンパクトなレコードをすぐに取得できます。

  オフラインで素早く対応したい、特定の購読者に関するサポートの問い合わせに使用します。

  beehiiv-pp-cli insights subscriber-lookup pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 [email protected] --agent --select subscription.email,subscription.status
  

• insights churn-sources — 購読解除につながる流入元、チャネル、キャンペーンを確認できます。

  購読解除が急増し、原因となっているチャネルをすぐに特定したい場合に使用します。

  beehiiv-pp-cli insights churn-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20 --agent
  

• insights send-times — 過去の実績をもとに、曜日と時間帯ごとの開封率を確認し、最適な配信時間を見つけられます。

  次の配信をスケジュールする際、習慣ではなく根拠に基づいて決めたい場合に使用します。

  beehiiv-pp-cli insights send-times pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent
  

• insights compare-publications — 同期済みのすべてのパブリケーションについて、成長とエンゲージメントを並べて比較できます。

  複数のパブリケーションを管理しており、クライアント向けレポートに比較表が必要な場合に使用します。

  beehiiv-pp-cli insights compare-publications --agent --select publications.name,publications.net_growth
  

コマンドリファレンス

advertisement-opportunities — 広告機会を管理する

• beehiiv-pp-cli advertisement-opportunities <publicationId> — 広告機会を取得する OAuth Scope: posts:read

authors — 著者を管理する

• beehiiv-pp-cli authors index — パブリケーションで利用可能な著者の一覧を取得します。
• beehiiv-pp-cli authors show — パブリケーションから単一の著者を取得します。

automations — オートメーションを管理します

• beehiiv-pp-cli automations index — オートメーションの一覧を取得します OAuth Scope: automations:read
• beehiiv-pp-cli automations show — オートメーションを取得します OAuth Scope: automations:read

bulk-subscription-updates — サブスクリプションの一括更新を管理します

• beehiiv-pp-cli bulk-subscription-updates index — サブスクリプション更新の一覧を取得します OAuth Scope: subscriptions:read
• beehiiv-pp-cli bulk-subscription-updates show — サブスクリプション更新を取得します OAuth Scope: subscriptions:read

bulk-subscriptions — サブスクリプションの一括操作を管理します

• beehiiv-pp-cli bulk-subscriptions <publicationId> — サブスクリプションを一括作成します OAuth Scope: subscriptions:write

complimentary-access — 無料アクセスを管理します

• beehiiv-pp-cli complimentary-access index — パブリケーションの無料アクセスオブジェクトを取得します。
• beehiiv-pp-cli complimentary-access show — 単一の無料アクセスオブジェクトを取得します。

condition-sets — 条件セットを管理します

• beehiiv-pp-cli condition-sets index — パブリケーションの有効な条件セットをすべて取得します。
• beehiiv-pp-cli condition-sets show — パブリケーションの有効な動的コンテンツ条件セットを1つ取得します。

custom-fields — カスタムフィールドを管理します

• beehiiv-pp-cli custom-fields create — カスタムフィールドを作成します OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields delete — カスタムフィールドを削除します OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields index — カスタムフィールドの一覧を取得します OAuth Scope: custom_fields:read
• beehiiv-pp-cli custom-fields patch — カスタムフィールドを更新します OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields put — カスタムフィールドを更新します OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields show — カスタムフィールドを取得します OAuth Scope: custom_fields:read

data-privacy — データプライバシーを管理します

• beehiiv-pp-cli data-privacy data-deletion-create — この機能は利用制限されており、有効化が必要です。
• beehiiv-pp-cli data-privacy data-deletion-index — この機能は利用制限されており、有効化が必要です。
• beehiiv-pp-cli data-privacy data-deletion-show — この機能は利用制限されており、有効化が必要です。

email-blasts — メール配信を管理します

• beehiiv-pp-cli email-blasts index — メール配信の一覧を取得します OAuth Scope: posts:read
• beehiiv-pp-cli email-blasts show — メール配信を取得します OAuth Scope: posts:read

engagements — エンゲージメントを管理します

• beehiiv-pp-cli engagements <publicationId> — 指定したパブリケーションのメールエンゲージメント指標を、指定した日付範囲と粒度で取得します。

exports — エクスポートを管理します

• beehiiv-pp-cli exports subscription-create — サブスクリプションのエクスポートを開始します。重複して開始する代わりに、進行中の既存のエクスポートを返します。
• beehiiv-pp-cli exports subscription-index — パブリケーションのサブスクリプションエクスポートを新しい順に一覧表示します。
• beehiiv-pp-cli exports subscription-show — サブスクリプションのエクスポートを取得します。ステータスが完了になるまでポーリングし、その後 download_url を読み取ります。有効化が必要な利用制限付き機能です。

newsletter-lists — ニュースレターのリストを管理します

• beehiiv-pp-cli newsletter-lists index — ニュースレターリストは現在ベータ版です。API は変更される可能性があります。
• beehiiv-pp-cli newsletter-lists show — ニュースレターリストは現在ベータ版です。API は変更される可能性があります。

podcasts — ポッドキャストを管理

• beehiiv-pp-cli podcasts index — パブリケーションのポッドキャストを一覧表示します。
• beehiiv-pp-cli podcasts show — 単一のポッドキャストを取得します。

polls — 投票を管理

• beehiiv-pp-cli polls index — 特定のパブリケーションに属するすべての投票を取得します。投票の選択肢は常に含まれます。
• beehiiv-pp-cli polls show — パブリケーションに属する特定の投票の詳細情報を取得します。

post-templates — 投稿テンプレートを管理

• beehiiv-pp-cli post-templates <publicationId> — パブリケーションで使用できる投稿テンプレートの一覧を取得します。

posts — 投稿を管理

• beehiiv-pp-cli posts aggregate-stats — 集計統計を取得します OAuth Scope: posts:read
• beehiiv-pp-cli posts create — この機能は現在ベータ版です。API は変更される可能性があります
• beehiiv-pp-cli posts delete — 投稿を削除またはアーカイブします。確定済みの投稿はステータスが archived に変更されます。
• beehiiv-pp-cli posts index — 投稿を一覧表示します OAuth Scope: posts:read
• beehiiv-pp-cli posts show — 投稿を取得します OAuth Scope: posts:read
• beehiiv-pp-cli posts update — この機能は現在ベータ版です。API は変更される可能性があります

publications — パブリケーションを管理

• beehiiv-pp-cli publications index — パブリケーションを一覧表示します OAuth Scope: publications:read
• beehiiv-pp-cli publications show — パブリケーションを取得します OAuth Scope: publications:read

referral-program — 紹介プログラムを管理

• beehiiv-pp-cli referral-program <publicationId> — 紹介プログラムを取得します OAuth Scope: referral_program:read

segments — セグメントを管理

• beehiiv-pp-cli segments create — 新しいセグメントを作成します。
• beehiiv-pp-cli segments delete — セグメントを削除します。セグメントを削除しても、そのセグメント内のサブスクリプションには影響しません。
• beehiiv-pp-cli segments index — セグメントを一覧表示します OAuth Scope: segments:read
• beehiiv-pp-cli segments show — セグメントを取得します OAuth Scope: segments:read

subscriptions — サブスクリプションを管理

• beehiiv-pp-cli subscriptions bulk-updates-patch — サブスクリプションを更新します OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions bulk-updates-patch-status — サブスクリプションのステータスを更新します OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions bulk-updates-put — サブスクリプションを更新します OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions bulk-updates-put-status — サブスクリプションのステータスを更新します OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions create — サブスクリプションを作成します OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions delete — これは取り消せません。サブスクリプションに関連付けられたすべてのデータも削除されます。
• beehiiv-pp-cli subscriptions get-by-email — このエンドポイントでは、メールアドレスを URL エンコードする必要があります。
• beehiiv-pp-cli subscriptions get-by-id — 以前の API バージョンには、subscriber ID でサブスクリプションを取得する別のエンドポイントがありました。
• beehiiv-pp-cli subscriptions get-by-subscriber-id — subscriber ID でサブスクリプションを取得します OAuth Scope: subscriptions:read
• beehiiv-pp-cli subscriptions index — 特定の publication に属するすべてのサブスクリプションを取得します。
• beehiiv-pp-cli subscriptions patch — ID でサブスクリプションを更新します OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions put — ID でサブスクリプションを更新します OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions update-by-email — メールアドレスでサブスクリプションを更新します OAuth Scope: subscriptions:write

tiers — ティアを管理します

• beehiiv-pp-cli tiers create — ティアを作成します OAuth Scope: tiers:write
• beehiiv-pp-cli tiers index — ティアを一覧表示します OAuth Scope: tiers:read
• beehiiv-pp-cli tiers patch — ティアを更新します OAuth Scope: tiers:write
• beehiiv-pp-cli tiers put — ティアを更新します OAuth Scope: tiers:write
• beehiiv-pp-cli tiers show — ティアを取得します OAuth Scope: tiers:read

users — ユーザーを管理します

• beehiiv-pp-cli users — ユーザーを識別します OAuth Scope: identify:read

webhooks — Webhook を管理します

• beehiiv-pp-cli webhooks create — Webhook を作成します OAuth Scope: webhooks:write
• beehiiv-pp-cli webhooks delete — Webhook を削除します OAuth Scope: webhooks:write
• beehiiv-pp-cli webhooks index — Webhook を一覧表示します OAuth Scope: webhooks:read
• beehiiv-pp-cli webhooks show — Webhook を取得します OAuth Scope: webhooks:read
• beehiiv-pp-cli webhooks update — Webhook を更新します OAuth Scope: webhooks:write

workspaces — ワークスペースを管理します

• beehiiv-pp-cli workspaces identify — ワークスペースを識別します OAuth Scope: identify:read
• beehiiv-pp-cli workspaces permissions-show — このワークスペースで OAuth トークンまたは API トークンに付与された権限を取得します。
• beehiiv-pp-cli workspaces publications-by-subscription-email — 指定されたメールアドレスのサブスクリプションがある、ワークスペース内のすべての publication を取得します。

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

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

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

which は、自然言語で記述された機能の問い合わせを、この CLI の厳選された機能インデックスから最も適したコマンドに対応付けます。終了コード 0 は少なくとも 1 つ一致したことを示し、終了コード 2 は確かな一致がなかったことを示します。その場合は --help を使うか、より絞り込んだ問い合わせをしてください。

レシピ

オーディエンスをミラーリングする

beehiiv-pp-cli sync --resources publications,subscriptions,segments,posts --max-pages 100

カーソルページネーションを使い、成長に不可欠な 4 つのエンティティを SQLite に同期します。

エージェント向けの成長スナップショット

beehiiv-pp-cli insights growth-summary pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent

ローカルストアから算出した、読み取り専用のヘルスサマリーです。

詳細な検索対象を絞り込む

beehiiv-pp-cli insights subscriber-lookup pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 [email protected] --agent --select subscription.email,subscription.status

--agent と --select のドット区切りパスを組み合わせ、エージェントが必要とするフィールドだけを返します。

解約急増の要因を特定する

beehiiv-pp-cli insights churn-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20

配信元、チャネル、UTM、リファラー別に、オフラインで購読解除をグループ化します。

購読者の CSV を出力する

beehiiv-pp-cli search "@example.com" --type subscriptions --limit 1000 --csv > subscribers.csv

すべてのリストコマンドと検索コマンドは、スプレッドシート用の CSV を出力します。

認証の設定

app.beehiiv.com（Settings > API Keys）で API キーを作成し、BEEHIIV_API_KEY をエクスポートします。このキーは組織にスコープされたベアラートークンです。毎分 180 件のリクエスト上限は、組織全体で共有されます。

beehiiv-pp-cli doctor を実行して、設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが有効になります：--json --compact --no-input --no-color。

• パイプ可能 — 標準出力には JSON、標準エラー出力にはエラーを出力します

• フィルタリング可能 — --select でフィールドの一部を選択できます。ドット区切りのパスはネストされた構造までたどり、配列は要素ごとに走査します。詳細な API でコンテキストを小さく保つために重要です。

  beehiiv-pp-cli advertisement-opportunities mock-value --agent --select advertisement_kind,advertiser_name,id
  

• プレビュー可能 — --dry-run で、送信せずにリクエストを表示します

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

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

• 明示的な確認 — --agent を指定しても --yes は暗黙に有効になりません。対象、引数、副作用が明確な場合に限り、別途 --yes を指定してください

• 明示的な再試行 — 既存の作成対象を成功として扱う場合に限り --idempotent を使用し、削除対象が存在しない場合を成功として扱う場合に限り --ignore-missing を使用してください

レスポンスエンベロープ

ローカルストアまたは API からデータを読み取るコマンドは、出力をデータの由来を示すエンベロープでラップします。

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

データには .results を、データがライブかローカルかの確認には .meta.source を解析してください。人間が読みやすい N results (live) というサマリーは、標準出力がターミナルで、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合にのみ、標準エラー出力に表示されます。パイプやエージェント経由で利用する場合、および出力形式を明示した場合は、標準出力に純粋な JSON が出力されます。

パスと状態

エージェントは、CLI のパス解決機能をランタイム契約の一部として扱う必要があります。

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

• 特定の種類だけを別の場所にする必要がある場合に限り、種類ごとの環境変数を使用します：BEEHIIV_CONFIG_DIR、BEEHIIV_DATA_DIR、BEEHIIV_STATE_DIR、BEEHIIV_CACHE_DIR。

• 解決順序は、種類ごとの環境変数、--home、BEEHIIV_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 から削除されます。

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

• MCP の場合は、MCP ホスト設定を通じてパスの変更を渡します。MCP バイナリは CLI フラグを引き継ぎません。

  {
    "mcpServers": {
      "beehiiv": {
        "command": "beehiiv-pp-mcp",
        "env": {
          "BEEHIIV_HOME": "/srv/beehiiv"
        }
      }
    }
  }
  

フリートでの優先順位：継承された種類ごとの環境変数は、その種類に対する明示的な --home より優先されます。永続的なフリート設定には BEEHIIV_HOME または種類ごとの環境変数を使用し、--home は 1 回の実行に限って使用してください。環境変数を解除しても、移動は元に戻りません。BEEHIIV_HOME を解除する前にファイルを手動で移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

自動学習

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

ステップ 1：何かを検索する前に recall

新しいユーザーの質問について、一覧表示／検索／詳細確認コマンドを実行する前に、次を実行します。

beehiiv-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>", "beehiiv-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 `beehiiv-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.

プレイブックと Notes は、リソースごとの手順とは独立しています。recall の応答にプレイブックと Results[] のヒットの両方が含まれる場合は、両方を使います。プレイブックは実行すべき一連の手順を示し、リソースのヒットは特定の手順を省略できるようにします。デフォルトでは mismatches を省略し、コールドスタート時の予想外の動作を調査する場合に限り --debug-mismatches を渡してください。

候補の判断について：learnings confirm <id> は候補を実体化する前に、その完全なペイロードを出力します。出力されたペイロードが、確認済みの動作と一致することを確認してください。learnings reject <id> は、導出シグネチャをトゥームストーン化し、同じ候補が再び表示されないようにします。エンベロープには、今対応する価値のある少数の候補のみが含まれます。未処理の候補全体は beehiiv-pp-cli learnings candidates で一覧表示できます。

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

Step 3: warnings は必ず確認する

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

Step 4: 応答を確定した後は、必ず teach & を実行する

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

beehiiv-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 は想起時にシード済みの entity_lookups を使ってエイリアスを横断した解決を行うため、あるエイリアスでの teach（例：「Niners」）は、別のエイリアス（例：「49ers」、「San Francisco」）での将来のクエリにも自動的に対応します。

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

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

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

# Common case: record both the resource learning AND the playbook in one call.
beehiiv-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).
beehiiv-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 と同様に、実行後の完了を待たずに進めます。

beehiiv-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 ではなく、個人用のノートに記録してください。

ループの測定

beehiiv-pp-cli learnings stats は、ローカルの learn_events テーブルから、再現率、教示内容の再利用率、プレイブックの解決率、候補の承認／却下件数を報告します。分母がない場合、率は null です。データはすべてこのマシン内に保持されます。このコマンドを使って、この CLI で学習ループが効果を発揮しているか確認してください。

学習を無効にする

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

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

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

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

エントリは、解決済みのデータディレクトリにある feedback.jsonl にローカル保存されます。BEEHIIV_FEEDBACK_ENDPOINT が設定され、かつ --send が指定されているか、BEEHIIV_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 ステータスを標準エラーに記録します。

名前付きプロファイル

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

beehiiv-pp-cli profile save briefing --json
beehiiv-pp-cli --profile briefing advertisement-opportunities mock-value
beehiiv-pp-cli profile list --json
beehiiv-pp-cli profile show briefing
beehiiv-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

この CLI の公開ライブラリエントリまたはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add beehiiv-pp-mcp -- beehiiv-pp-mcp

確認するには、claude mcp list を実行します。

直接使用

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

   beehiiv-pp-cli <command> [subcommand] [args] --agent
   

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