agent-notion

agent-notion による Notion の自動化

agent-notion は、$PATH にインストールされる CLI バイナリです。直接実行してください（例：agent-notion search query "Project Plan"）。

出力は NDJSON です — 標準出力に 1 行につき 1 つの JSON レコードが出力されます。リストコマンドは項目ごとに 1 つのレコードを出力し、さらに項目がある場合は末尾に {"@pagination": {...}}（または {"@meta": ...}／{"@total": n}）の行が続きます。代わりに --format json|yaml を渡すと、{ "data": [ … ] } 形式の整形済みエンベロープが 1 つ出力されます。--format jsonl はデフォルトの NDJSON 形式です。

エラーは、終了コード 1 で { "error": "...", "fixable_by": "agent|human|retry", "hint": "..." } の形式で標準エラー出力に出力されます。トークンが出力されることはありません。

バックエンド

API バックエンドは 2 種類あります。公式 REST API（インテグレーショントークン、OAuth）と、v3 デスクトップセッション API（auth import-desktop／import-browser）です。--backend auto（デフォルト）は、保存済みの v3 セッションがあれば優先し、なければ公式の認証情報を使用します。--backend official または --backend v3 を指定して、使用するバックエンドを固定できます。次のコマンドには v3 セッションが必要です：export、page backlinks、page history、activity log、page archive／unarchive、block move、comment inline、およびすべての ai コマンド。

クイックスタート（認証）

オプション A：OAuth（公式 API の全機能を利用する場合に推奨）

agent-notion auth setup-oauth --client-id <id> --client-secret <secret>
agent-notion auth login                        # opens the browser for the OAuth flow
agent-notion auth status

オプション B：内部インテグレーショントークン

シークレットが argv、シェルの履歴、エージェントのトランスクリプトに残らないよう、標準入力経由でトークンを渡してください。

printf '%s' "$NOTION_TOKEN" | agent-notion auth import   # token read from stdin
agent-notion auth status

トークンは保存前に API に対して検証されます。エイリアスはワークスペース名から導出されます（--alias で上書きできます）。

トークンを自分で --token に貼り付けないでください。 ユーザーがチャットに ntn_…／secret_… インテグレーショントークンを貼り付けた場合、それを --token に指定しないでください — シークレットがコンテキストウィンドウ、トランスクリプト、後続のテレメトリーに記録されてしまいます。代わりに、ユーザー自身でインポートを実行するよう案内してください（上記のように標準入力経由で渡すか、ユーザー自身のターミナルで --token を使用します）。そうすれば、シークレットが LLM に渡ることはありません。人が対話的にセットアップする場合は、OAuth（オプション A）またはデスクトップ／ブラウザーセッション（オプション C）を推奨します。これらの方法では、トークンそのものがエージェントを経由することはありません。

オプション C：デスクトップセッション（v3 の機能を使う場合）

agent-notion auth import-desktop                       # reads token_v2 from the Notion Desktop app
agent-notion auth import-browser chrome                # or from a browser cookie store

import-browser が対応しているブラウザー：chrome、brave、edge、arc、chromium、firefox、zen、safari（プロファイルを選択する場合は --profile <p> を指定します）。

複数のワークスペースに対応しています。

agent-notion auth login --alias work
agent-notion auth workspace list
agent-notion auth workspace switch <alias>
agent-notion auth workspace remove <alias> --yes       # destructive: needs --yes
agent-notion auth logout --yes                          # default workspace; --all wipes everything

検索

重要：Notion の検索対象はタイトルのみです。 ページのコンテンツ、コメント、プロパティ値は検索されません。コンテンツ内を検索するには、プロパティフィルターを指定して database query <id> を使用するか、block list <page-id> を実行して出力を grep してください。

agent-notion search query "meeting notes"
agent-notion search query "Q1 Plan" --filter database
agent-notion search query "design doc" --filter page --limit 5

各検索結果は 1 つの NDJSON レコード {id, type, title, url, parent?, last_edited_at?} です。さらに検索結果がある場合は、末尾に {"@pagination": {has_more, next_cursor}} の行が表示されます（--cursor を使って next_cursor を次のリクエストに渡してください）。

データベース

agent-notion database list                                          # via the search API
agent-notion database get <database-id>                             # full metadata + property definitions
agent-notion database schema <database-id>                          # compact schema (types, options) for LLMs
agent-notion database query <database-id>                           # rows (one NDJSON record each)
agent-notion database query <id> --filter '{"property":"Status","status":{"equals":"Done"}}'
agent-notion database query <id> --sort '[{"property":"Name","direction":"ascending"}]'

フィルターを作成する前に database schema を使用して、プロパティ名、型、有効なセレクト／ステータスの選択肢を確認してください。

結果の順序： --sort を指定しない場合、行はビュー独自の順序（多くの場合は手動設定）で返され、新しい順にはなりません — 追加したばかりの行が最後に並ぶことがあり、その場合は --limit によってその行が何も通知されずに除外され、行が見つからないように見えます。「最新の N 件」を取得する場合は、必ずタイムスタンプで --sort を指定してください：--sort '[{"timestamp":"last_edited_time","direction":"descending"}]'。{"@pagination": {has_more, next_cursor}} の末尾行を確認すれば、結果が途中で切られているのか、それ以上の行がないのかを判別できます。

ページの parent.id（そのデータベースの ID）は、データベースビューを開く際に使った ID と異なる場合でも、database get／query／schema で使用できます。行の parent を取得して、そのデータベースを直接クエリできます。

ページ

agent-notion page get <page-id>                                     # properties only
agent-notion page get <page-id> --content                           # properties + markdown content
agent-notion page get <page-id> --raw-content                       # properties + structured block objects
agent-notion page create --parent <id> --title "New Page"           # auto-detects database vs page parent
agent-notion page create --parent <db-id> --title "Task" --properties '{"Status":"In Progress","Priority":"High"}'
agent-notion page create --parent <id> --title "Notes" --icon "📝"
agent-notion page update <page-id> --title "Updated Title"          # at least one of --title/--properties/--icon
agent-notion page update <page-id> --properties '{"Status":"Done"}' --icon "✅"
agent-notion page trash <page-id> --yes                             # move to Trash (recoverable; destructive)
agent-notion page restore <page-id>                                 # restore from Trash
agent-notion page archive <page-id> --yes                           # real Archive (v3-only; destructive)
agent-notion page unarchive <page-id>                               # undo real Archive (v3-only)

アーカイブとゴミ箱は、Notion の独立した状態です。ゴミ箱に入れると alive=false に設定され、すべてのバックエンドで利用できます。アーカイブするとページは検索結果に表示されなくなりますが、ページは有効な状態のままで、v3 バックエンドが必要です。ページは、どちらか一方、両方、またはいずれの状態にもなれます。

--content／--raw-content を指定すると、block_count と content_truncated が追加されます（ページに 1000 を超えるブロックがある場合は true）。--properties のプロパティ値は自動変換されます。文字列はセレクト値、数値は数値プロパティ、真偽値はチェックボックス、配列はマルチセレクトに変換されます。複雑な型には Notion API 形式を渡してください。

ブロック（ページコンテンツ）

agent-notion block list <page-id>                                   # markdown (default): {page_id, content, block_count, has_more}
agent-notion block list <page-id> --raw                             # one NDJSON record per block {id, type, content, has_children}
agent-notion block append <page-id> --content "## New Section\n\nParagraph text"
agent-notion block append <page-id> --blocks '[{"type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Hello"}}]}}]'
agent-notion block update <block-id> --content "New text"           # replace a single block's text
agent-notion block delete <block-id> --yes                          # destructive: needs --yes
agent-notion block move <block-id> --after <other-block-id>         # reorder (v3)
agent-notion block move <block-id> --parent <callout-id>            # move into a container (v3)
agent-notion block replace <page-id> --content "# Fresh\n\nAll new" --yes   # delete all blocks, then append (destructive)

Markdown 変換では、見出し、リスト、ToDo、コードフェンス、引用、コールアウト、画像、区切り線、テーブル（GitHub Flavored Markdown のパイプ形式のテーブルとしてレンダリングされ、最初の行がヘッダーになります。--raw の table_row レコードには cells 配列が含まれます）に対応しています。update／delete に使うブロック ID を取得するには、block list --raw を使用してください。block replace は既存のすべてのブロックを削除してから追加するため、--yes が必要です。

コメント

agent-notion comment list <page-id>
agent-notion comment page <page-id> "This looks good!"
agent-notion comment inline <block-id> "Great point!" --text "target phrase"       # v3
agent-notion comment inline <block-id> "Second one" --text "the" --occurrence 2    # v3

comment list は、コメントごとに 1 つの NDJSON レコード {id, body, author: {id, name}, created_at} を出力します。comment page は {id, discussion_id, body, created_at} を返します。comment inline は anchor_text を追加し、v3 デスクトップセッションが必要です。ディスカッションスレッドには対応していません（すべてのコメントはトップレベルです）。API ではコメントの編集や削除はできません。

v3 の機能（auth import-desktop が必要です）

エクスポート

agent-notion export page <page-id>                             # export as a markdown zip
agent-notion export page <page-id> --format html --recursive   # export the page tree as HTML
agent-notion export workspace                                  # export the entire workspace
agent-notion export workspace --output my-backup.zip           # custom output path
agent-notion export poll <task-id> --output backup.zip         # resume a timed-out export

オプション：--format markdown|html、--recursive（ページのみ）、--output <path>、--wait <seconds>（ページのデフォルトは 120、ワークスペース／ポーリングのデフォルトは 600）。エクスポートは非同期で実行されます。CLI は完了するか --wait のタイムアウトに達するまでポーリングし、その後タスク ID を出力します。これを使って export poll で再開できます。進行状況は stderr に出力されます。出力：{exported, format, pages_exported, recursive?}。exported は絶対パスの zip ファイルです。

バックリンク

agent-notion page backlinks <page-id>                          # pages linking to this page (v3)

ソースページごとに NDJSON レコード {block_id, page_id, page_title} を 1 つ出力します（ページ単位で重複排除）。その後に {"@total": n} を出力します。

履歴

agent-notion page history <page-id>                            # version snapshots (v3)
agent-notion page history <page-id> --limit 50

スナップショットごとに NDJSON レコード {id, version, last_version, timestamp, authors} を 1 つ出力します。その後に {"@total": n} を出力します。

アクティビティ

agent-notion activity log                                      # workspace-wide activity (v3)
agent-notion activity log --page <page-id>                     # scoped to a page
agent-notion activity log --limit 50

アクティビティごとに NDJSON レコード {id, type, page_id, page_title, authors, edit_types, start_time, end_time} を 1 つ出力します。

Notion AI（auth import-desktop が必要です）

agent-notion ai model list                                         # active models (name, family, tier)
agent-notion ai model list --raw                                   # full model objects incl. codenames
agent-notion ai chat list [--limit 10]                             # recent threads
agent-notion ai chat get <thread-id>                               # thread messages
agent-notion ai chat send "Summarize my recent projects"           # new conversation
agent-notion ai chat send "Tell me more" --thread <id>             # continue a thread
agent-notion ai chat send "Explain this page" --page <page-id>     # with page context
agent-notion ai chat send "Summarize this" --page <page-id> --read-only  # ask/answer only, no edits
agent-notion ai chat send "Quick question" --stream                # stream response text to stderr
agent-notion ai chat send "Hello" --model "GPT-5.2"                # specific model
agent-notion ai chat mark-read <thread-id>

ai chat send は {thread_id, response, title, model, tokens: {input, output, cached}} を返します。モデルの解決順序は、--model フラグ、設定の ai.default_model、API のデフォルトです。コードネーム（例：oatmeal-cookie）または表示名を指定できます。--stream を指定すると、レスポンスのテキストは stderr にストリーミングされ、JSON の結果は引き続き stdout に出力されます。

デフォルトでは、AI は Notion と同等のドキュメント編集ツールを利用できるため、プロンプトによってページを変更できます。質問と回答のみのモードをリクエストするには、--read-only を渡してください。Notion のバックエンドにツールの無効化を依頼します（クライアント側で強制される保証ではなく、サーバー側へのリクエストです）。

ユーザー

agent-notion user list                                              # one NDJSON record per user {id, name, type, email?, avatar_url?}
agent-notion user me                                                # bot identity {id, name, type, workspace_name}

type は person または bot です。email は person ユーザーにのみ含まれます。

切り詰め

description、body、content という名前のフィールドは、デフォルトで 200 文字に切り詰められます。対応する {field}Length フィールド（例：descriptionLength）には、常に全文のルーン数が含まれるため、エージェントはコンテンツが切り詰められたかどうかを判断できます。上限を引き上げるか、フィールドを展開してください。

agent-notion --full page get <page-id>                              # expand every truncatable field
agent-notion --expand description database get <id>                 # expand one field
agent-notion --expand description,content page get <id> --content   # expand several
agent-notion config set truncation.max_length 500                   # raise the default cap

--expand／--full はグローバルフラグです（コマンドの前後どちらにも指定できます）。

グローバルフラグ

• --backend auto|official|v3 — API バックエンドを選択します（デフォルトは auto）
• --format json|yaml|jsonl — json／yaml は出力を 1 つの整形済み {data: […]} エンベロープで囲みます。jsonl はデフォルトの NDJSON です
• --expand <fields>／--full — フィールドの切り詰めを解除します
• --color auto|always|never、--timeout <ms>、--debug、--version

ID

コマンドでは、ハイフンあり／なしの Notion UUID を指定できます（URL のハイフンなし ID は自動的に正規化されます）。

• a1b2c3d4-1111-2222-3333-444444444444
• a1b2c3d411112222333344444444444444

ページネーション

一覧コマンドは NDJSON レコードをストリーミングし、結果がさらにある場合は {"@pagination": {has_more, next_cursor}} のトレーラーを出力します。ページをめくるには、--limit <n>（最大 100）と --cursor <token> を渡します。--format json|yaml の場合、レコードとページネーション情報は 1 つの {data: […], "@pagination": …} エンベロープにまとめられます。

破壊的なコマンド（--yes が必要）

page trash、page archive、block delete、block replace、auth logout、auth workspace remove は状態を変更するため、--yes がないと実行を拒否します。指定しない場合、実行内容を説明する fixable_by: human エラーを返します。page restore と page unarchive は対象外です。

コマンドごとの使用方法ドキュメント

すべてのグループには、詳細で LLM 向けに最適化されたドキュメントを提供する usage サブコマンドがあります。

agent-notion usage                # top-level overview
agent-notion search usage
agent-notion database usage
agent-notion page usage
agent-notion block usage
agent-notion comment usage
agent-notion export usage
agent-notion activity usage
agent-notion ai usage
agent-notion user usage
agent-notion auth usage
agent-notion config usage

操作前にドメインの詳細を確認する必要がある場合は、agent-notion <group> usage を実行してください。

設定

agent-notion config list                                            # every key with value + description
agent-notion config get <key>                                       # one setting {key, value, set}
agent-notion config set truncation.max_length 500                   # raise the truncation cap
agent-notion config set page_size 20                                # default results per list command (1-100)
agent-notion config set ai.default_model <codename>                 # default AI model
agent-notion config unset <key>                                     # reset one key to its default

キー：page_size、max_depth、truncation.max_length、ai.default_model。設定は ~/.config/agent-notion/config.json に保存されます。

参考資料

• references/commands.md：コマンドの全体像とすべてのフラグ
• references/output.md：NDJSON 出力形式とフィールドの詳細