pp-notion

Notion — Printing Press CLI

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

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

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

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

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

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、直接 Go を使ったインストールに切り替えてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/productivity/notion/cmd/notion-pp-cli@latest

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

この CLI を使う場面

ターミナルから Notion のページやブロックを管理したり、古くなったページを検出したり、指定した時点以降の変更を追跡したりする場合は、notion-pp-cli を使ってください。まず sync を一度実行してローカルストアにデータを取り込みます。その後は stale と changed をオフラインで実行できます。日常的な編集で Notion のウェブ UI の代わりに使うものではありません。

独自の機能

この API 用のほかのツールでは利用できない機能です。

エージェント向けの連携機能

• changed — 最後の同期時点、または指定したタイムスタンプ以降にワークスペースで追加、編集、削除されたすべての内容を表示します。

  エージェントセッションの開始時に使うと、操作を始める前に変更内容を把握できます。

  notion-pp-cli changed --since 2h --json
  

蓄積されるローカル状態

• stale — N 日間編集されていないページやレコードを一覧表示します。データベース、親、タグで絞り込めます。

  ワークスペースを整理する前に使って放置されたページを特定したり、レビュー期限を過ぎた成果物にフラグを付けたりできます。

  notion-pp-cli stale --days 30 --db ProjectDB --agent
  

コマンドリファレンス

blocks — ブロックのエンドポイント

• notion-pp-cli blocks delete — ブロックを削除
• notion-pp-cli blocks query-meeting-notes — 会議メモを検索
• notion-pp-cli blocks get — ID でブロックを取得
• notion-pp-cli blocks update — ブロックを更新
• notion-pp-cli blocks children list — ブロックまたはページの子要素を一覧表示
• notion-pp-cli blocks children append — ページまたはブロックにブロックを追加

comments — コメントのエンドポイント

• notion-pp-cli comments create-a — コメントを作成
• notion-pp-cli comments delete-a — コメントを削除
• notion-pp-cli comments list — コメントを一覧表示
• notion-pp-cli comments retrieve — コメントを取得
• notion-pp-cli comments update-a — コメントを更新

custom-emojis — カスタム絵文字のエンドポイント

• notion-pp-cli custom-emojis — カスタム絵文字を一覧表示

data-sources — データソースのエンドポイント

• notion-pp-cli data-sources create-a-database — データソースを作成
• notion-pp-cli data-sources retrieve-a — データソースを取得
• notion-pp-cli data-sources update-a — データソースを更新
• notion-pp-cli data-sources query post-database <data_source_id> — データソースを検索します。注：末端のコマンドは単独の query ではなく post-database です。data-sources query はヘルプを表示する中間グループです。これは、直接実行される databases query <id> とは異なります。

databases — データベースのエンドポイント

• notion-pp-cli databases query <database_id> — 任意のフィルター／ソートを指定して、データベース内のレコードを検索
• notion-pp-cli databases create — データベースを作成
• notion-pp-cli databases retrieve — データベースを取得
• notion-pp-cli databases update — データベースを更新

file-uploads — ファイルアップロードのエンドポイント

• notion-pp-cli file-uploads create-file — ファイルアップロードを作成
• notion-pp-cli file-uploads list — ファイルアップロードを一覧表示
• notion-pp-cli file-uploads retrieve — ファイルアップロードを取得

notion-search — Notion 検索を管理

• notion-pp-cli notion-search — タイトルで検索

oauth — OAuth のエンドポイント（基本認証）

• notion-pp-cli oauth create-a-token — 認証コードをアクセストークンとリフレッシュトークンに交換
• notion-pp-cli oauth introspect-token — トークンを調査
• notion-pp-cli oauth revoke-token — トークンを取り消し

pages — ページのエンドポイント

• notion-pp-cli pages update — ページを更新
• notion-pp-cli pages create — ページを作成
• notion-pp-cli pages get — ID でページを取得
• notion-pp-cli pages move — ページを移動
• notion-pp-cli pages markdown export — ページを Markdown としてエクスポート

users — ユーザーのエンドポイント

• notion-pp-cli users get — すべてのユーザーを一覧表示
• notion-pp-cli users get-self — トークンに紐づくボットユーザーを取得
• notion-pp-cli users get-userid — ユーザーを取得

views — ビューのエンドポイント

• notion-pp-cli views create — ビューを作成
• notion-pp-cli views delete — ビューを削除
• notion-pp-cli views list — ビューを一覧表示
• notion-pp-cli views retrieve-a — ビューを取得
• notion-pp-cli views update-a — ビューを更新

sync pages — すべてのページとデータベースをローカルの SQLite に同期

• notion-pp-cli sync pages — 検索 API 経由ですべてのページとデータベースを同期（stale/changed の実行前に実行）
• notion-pp-cli sync pages --full — 最初から完全に再同期
• notion-pp-cli sync pages --type database — データベースのみを同期

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

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

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

which は自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに解決します。終了コード 0 は少なくとも 1 件の候補が見つかったことを示します。終了コード 2 は確度の高い候補が見つからなかったことを示すため、--help を使用するか、より範囲を絞った問い合わせを行ってください。

レシピ

朝のトリアージ：夜間に変更された内容

notion-pp-cli changed --since 8h --json

直近 8 時間に編集されたものをすべて表示します。セッション開始時に実行すると、操作を始める前に状況を把握できます。

クリーンアップ前に古いページを見つける

notion-pp-cli stale --days 30 --json --select id,title,days_since_edit,last_edited_time

30 日以上更新されていないページを、古い順に並べます。Notion の UI には、複数のワークスペースを対象にした同等のフィルターはありません。

ページを Markdown としてエクスポートする

notion-pp-cli pages markdown export <page-id>

ネイティブの Notion Markdown エンドポイント経由でページの内容を Markdown として取得します。変換は不要です。

ページのブロックの子要素を読み取る

notion-pp-cli blocks children list <page-id> --json --select id,type

ページ上の最上位ブロックをすべて、種類と ID とともに一覧表示します。

認証の設定

Notion Internal Integration トークンが必要です。notion.so/my-integrations で作成し、最上位のページを共有したうえで、環境に NOTION_BEARER_AUTH（または NOTION_TOKEN）を設定してください。

初回セットアップ：

notion-pp-cli doctor          # verify auth
notion-pp-cli sync pages      # sync all pages + databases (~15k pages, takes 2-3 min)
notion-pp-cli stale --days 30 # now works
notion-pp-cli changed --since 24h

notion-pp-cli doctor を実行して、セットアップを確認してください。

エージェントモード

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

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

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

  notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --agent --select id,name,status
  

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

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

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

• 明示的な再試行 — 既存の作成対象を成功として扱う場合に限り --idempotent を使い、削除対象が見つからない場合を成功として扱う場合に限り --ignore-missing を使います

レスポンスエンベロープ

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

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

データには .results を解析し、ライブデータかローカルデータかを確認するには .meta.source を参照してください。人が読める N results (live) という概要は、標準出力がターミナルの場合にのみ標準エラー出力に表示されます。パイプ／エージェントの利用者には、標準出力に純粋な JSON が出力されます。

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

この CLI に問題があることに（あなた、またはエージェントが）気づいたら、記録してください：

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

記録は ~/.notion-pp-cli/feedback.jsonl にローカル保存されます。NOTION_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか NOTION_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 ステータスを標準エラー出力に記録します。

名前付きプロファイル

プロファイルは、保存したフラグ値のセットで、実行ごとに再利用できます。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは HeyGen の「Beacon」パターンです。

notion-pp-cli profile save briefing --json
notion-pp-cli --profile briefing comments list --block-id 550e8400-e29b-41d4-a716-446655440000
notion-pp-cli profile list --json
notion-pp-cli profile show briefing
notion-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します：

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

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

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

   go install github.com/mvanhorn/printing-press-library/library/productivity/notion/cmd/notion-pp-mcp@latest
   

2. Claude Code に登録します：

   claude mcp add notion-pp-mcp -- notion-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

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

4. 曖昧な場合は、サブコマンドのヘルプを確認します。機械可読なコマンド／フラグの情報が必要な場合は、notion-pp-cli <command> --help --agent を使用します。--help のみの場合は、人が読みやすい形式で表示されます。