vibe-notionbot

Vibe Notionbot

AI エージェントと人間が、公式 Notion API を通じて Notion ワークスペースを操作できる TypeScript CLI ツールです。ページ、データベース、ブロック、ユーザー、コメント、検索に対応しています。

使用する CLI

このパッケージには 2 つの CLI が含まれています。状況に応じて適切なものを選んでください。

	vibe-notion	vibe-notionbot（この CLI）
API	非公式のプライベート API	公式 Notion API
認証	Notion デスクトップアプリから token_v2 を自動抽出	NOTION_TOKEN 環境変数（インテグレーショントークン）
ID	ユーザーとして動作	ボットとして動作
セットアップ	不要 — 認証情報を自動抽出	手動 — notion.so/my-integrations でインテグレーションを作成
データベースの行	add-row、update-row	page create --database で作成
ビュー管理	view-get、view-update、view-list、view-add、view-delete	非対応
ワークスペース一覧表示	対応	非対応
安定性	プライベート API — Notion の変更により動作しなくなる可能性があります	公式のバージョン管理された API — 安定

選択の流れ：

1. Notion デスクトップアプリがインストールされている場合 → vibe-notion を使用します
2. デスクトップアプリはなく、NOTION_TOKEN が設定されている場合 → vibe-notionbot（この CLI）を使用します
3. 両方を利用できる場合 → vibe-notion を優先します（機能が幅広く、セットアップ不要）
4. どちらも利用できない場合 → 2 つのうちいずれかを設定するようユーザーに依頼します

重要：CLI のみを使用

Notion API を直接呼び出さないでください。 常に、このスキルで説明されている vibe-notionbot CLI コマンドを使用してください。Notion API に対して生の HTTP リクエストを送信したり、@notionhq/client を直接使用したりしないでください。API を直接呼び出すと、認証情報が漏えいするリスクがあり、Notion の不正利用検出が作動してユーザーのアカウントがブロックされる可能性があります。

必要な機能が vibe-notionbot でサポートされていない場合は、その旨をユーザーに伝え、ユーザーに代わって devxoul/vibe-notion への機能リクエストを提出することを提案してください。提出する前に、実際のユーザーデータ（ID、名前、メールアドレス、トークン、ページ内容など、ユーザーやそのワークスペースを特定できる情報）をすべて取り除いてください。代わりに汎用的なプレースホルダーを使い、未対応機能の説明に絞った Issue にしてください。

重要：スクリプトを書かない

Notion 操作を自動化するためのスクリプト（Python、TypeScript、Bash など）を書かないでください。 batch コマンドは、規模を問わず一括操作に対応しています。API 呼び出しをループするスクリプトを書くのは常に誤りです。代わりに --file を指定して batch を使用してください。

次の場合も同様です。

• 100 件以上の行やページを作成する必要がある場合
• 新しく作成する項目間で相互参照が必要な場合（マルチパス batch を使用してください。一括操作の戦略を参照）
• 1 つのコマンドには「大きすぎる」と感じる操作の場合

「このためのスクリプトを書くべきだ」と考えたら、そこで止めて batch を使用してください。

クイックスタート

# Check authentication status
vibe-notionbot auth status

# Search for a page or database
vibe-notionbot search "Project Roadmap"

# List all databases
vibe-notionbot database list

# Create a new page
vibe-notionbot page create --parent <parent_id> --title "My New Page"

認証

インテグレーショントークン（公式 API）

Notion Developer Portal で取得したインテグレーショントークンを使って、NOTION_TOKEN 環境変数を設定します。

export NOTION_TOKEN=secret_xxx
vibe-notionbot auth status

インテグレーショントークンを使うと、公式 Notion API（@notionhq/client）にアクセスできます。

コマンド

ページコマンド

# Retrieve a page
vibe-notionbot page get <page_id>

# Create a new page under a parent page or database
vibe-notionbot page create --parent <parent_id> --title "New Page Title"
vibe-notionbot page create --parent <database_id> --title "New Database Item" --database

# Create a page with markdown content
vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown '# Hello\n\nThis is **bold** text.'

# Create a page with markdown from a file
vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown-file ./content.md

# Create a page with markdown containing local images (auto-uploaded to Notion)
vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown-file ./doc-with-images.md

# Update page properties
vibe-notionbot page update <page_id> --set "Status=In Progress" --set "Priority=High"

# Replace all content on a page with new markdown
vibe-notionbot page update <page_id> --replace-content --markdown '# New Content'
vibe-notionbot page update <page_id> --replace-content --markdown-file ./updated.md

# Archive (delete) a page
vibe-notionbot page archive <page_id>

# Retrieve a specific page property
vibe-notionbot page property <page_id> <property_id>

データベースコマンド

# Retrieve a database schema
vibe-notionbot database get <database_id>

# Query a database with optional filters and sorts
vibe-notionbot database query <database_id> --filter '{"property": "Status", "select": {"equals": "In Progress"}}'
vibe-notionbot database query <database_id> --sort '[{"property": "Created time", "direction": "descending"}]'
vibe-notionbot database query <database_id> --page-size 10 --start-cursor <cursor>

# Create a database under a parent page
vibe-notionbot database create --parent <page_id> --title "My Database" --properties '{"Name": {"title": {}}}'

# Update a database schema or title
vibe-notionbot database update <database_id> --title "Updated Title"
vibe-notionbot database update <database_id> --properties '{"Status": {"select": {"options": [{"name": "Active"}, {"name": "Archived"}]}}}'
vibe-notionbot database update <database_id> --title "Updated Title" --properties '{"Status": {"select": {}}}'

# Delete a property from a database
vibe-notionbot database delete-property <database_id> --property "Status"

# List all databases accessible by the integration
vibe-notionbot database list
vibe-notionbot database list --page-size 10 --start-cursor <cursor>

ブロックコマンド

# Retrieve a block
vibe-notionbot block get <block_id>

# List direct children of a block (paginated)
vibe-notionbot block children <block_id>
vibe-notionbot block children <block_id> --page-size 50 --start-cursor <cursor>

# Append child blocks to a parent
vibe-notionbot block append <parent_id> --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Hello World"}}]}}]'

# Append markdown content as blocks
vibe-notionbot block append <parent_id> --markdown '# Hello\n\nThis is **bold** text.'

# Append markdown from a file
vibe-notionbot block append <parent_id> --markdown-file ./content.md

# Append markdown with local images (auto-uploaded to Notion)
vibe-notionbot block append <parent_id> --markdown-file ./doc-with-images.md

# Append nested markdown (indented lists become nested children blocks)
vibe-notionbot block append <parent_id> --markdown '- Parent item\n  - Child item\n    - Grandchild item'

# Append blocks after a specific block (positional insertion)
vibe-notionbot block append <parent_id> --after <block_id> --markdown '# Inserted after specific block'
vibe-notionbot block append <parent_id> --after <block_id> --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Inserted after"}}]}}]'

# Append blocks before a specific block
vibe-notionbot block append <parent_id> --before <block_id> --markdown '# Inserted before specific block'

# Update a block's content
vibe-notionbot block update <block_id> --content '{"paragraph": {"rich_text": [{"type": "text", "text": {"content": "Updated content"}}]}}'

# Delete (archive) a block
vibe-notionbot block delete <block_id>

# Upload a file as a block (image or file block)
vibe-notionbot block upload <parent_id> --file ./image.png --pretty
vibe-notionbot block upload <parent_id> --file ./document.pdf --pretty
vibe-notionbot block upload <parent_id> --file ./image.png --after <block_id> --pretty
vibe-notionbot block upload <parent_id> --file ./image.png --before <block_id> --pretty

ユーザーコマンド

# List all users in the workspace
vibe-notionbot user list
vibe-notionbot user list --page-size 10 --start-cursor <cursor>

# Get info for a specific user
vibe-notionbot user get <user_id>

# Get info for the current bot/integration
vibe-notionbot user me

検索コマンド

# Search across the entire workspace
vibe-notionbot search "query text"

# Filter search by object type
vibe-notionbot search "Project" --filter page
vibe-notionbot search "Tasks" --filter database

# Sort search results
vibe-notionbot search "Meeting" --sort desc

# Paginate search results
vibe-notionbot search "Notes" --page-size 10 --start-cursor <cursor>

コメントコマンド

# List comments on a page
vibe-notionbot comment list --page <page_id>
vibe-notionbot comment list --page <page_id> --page-size 10 --start-cursor <cursor>

# List inline comments on a specific block
vibe-notionbot comment list --block <block_id>

# Create a comment on a page
vibe-notionbot comment create "This is a comment" --page <page_id>

# Reply to a comment thread (discussion)
vibe-notionbot comment create "Replying to thread" --discussion <discussion_id>

# Retrieve a specific comment
vibe-notionbot comment get <comment_id>

バッチ操作

複数の書き込み操作を、1 回の CLI 呼び出しで実行します。一度に複数の項目を作成、更新、削除する場合は、CLI を繰り返し呼び出す代わりにこちらを使用してください。トークンを節約し、ラウンドトリップを減らせます。

# Inline JSON (no --workspace-id needed, uses NOTION_TOKEN)
vibe-notionbot batch '<operations_json>'

# From file (for large payloads)
vibe-notionbot batch --file ./operations.json '[]'

サポートされているアクション（全 11 種類）：

アクション	説明
page.create	ページを作成
page.update	ページのプロパティを更新
page.archive	ページをアーカイブ
block.append	親にブロックを追加
block.update	ブロックを更新
block.delete	ブロックを削除
comment.create	コメントを作成
database.create	データベースを作成
database.update	データベースのタイトルまたはスキーマを更新
database.delete-property	データベースのプロパティを削除
block.upload	ファイルを画像またはファイルブロックとしてアップロード

操作の形式：各操作は、action と、個々のコマンドハンドラーに渡すものと同じフィールドを持つオブジェクトです。異なるアクションを組み合わせた例：

[
  {"action": "page.create", "parent": "<parent_id>", "title": "Meeting Notes"},
  {"action": "block.append", "parent_id": "<page_id>", "markdown": "# Agenda\n\n- Item 1\n- Item 2"},
  {"action": "comment.create", "content": "Page created via batch", "page": "<page_id>"}
]

出力形式：

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"id": "page-uuid", "...": "..."}},
    {"index": 1, "action": "block.append", "success": true, "data": {"...": "..."}},
    {"index": 2, "action": "comment.create", "success": true, "data": {"id": "comment-uuid", "...": "..."}}
  ],
  "total": 3,
  "succeeded": 3,
  "failed": 0
}

フェイルファストの動作：操作は順番に実行されます。いずれかの操作が失敗すると、実行は直ちに停止します。出力には、完了したすべての操作と失敗した操作の結果が含まれます。失敗時はプロセスが終了コード 1 で、成功時は 0 で終了します。

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"...": "..."}},
    {"index": 1, "action": "block.append", "success": false, "error": "Block not found"}
  ],
  "total": 3,
  "succeeded": 1,
  "failed": 1
}

一括操作の戦略

大規模な操作（数十から数百の項目）では、シェルの引数制限を回避し、管理しやすくするために --file を使用してください。

手順 1：操作の JSON をファイルに書き込み、--file を指定してバッチを実行します。

# Write operations to a file (using your Write tool), then:
vibe-notionbot batch --file ./operations.json '[]'

複数パスのパターン — 新しい項目同士が互いを参照する必要がある場合（たとえば、新しく作成した別のページにリンクするページプロパティ）：

1. パス 1 — すべての項目を作成（相互参照なし）：他の新しい項目を参照するプロパティを省略し、すべての作成操作を含むバッチ JSON ファイルを書き込みます。実行後、出力から返された ID を収集します。
2. パス 2 — 相互参照を設定：パス 1 で取得した ID を使用して参照プロパティを設定する更新操作を含む、2 つ目のバッチ JSON ファイルを書き込みます。実行します。

Pass 1: Create items A, B, C (no cross-refs) → get IDs for A, B, C
Pass 2: Update A.related=B, C.parent_ref=A (using real IDs from Pass 1)

これはスクリプトを使う場合と同じ結果ですが、コードを書く必要はありません。バッチ呼び出しは 2 回だけです。

レート制限

Notion は API にレート制限を設けています。バッチ操作は順番に実行されるため、大きなバッチ（30 件以上）では 429 Too Many Requests エラーが発生する場合があります。これを避けるには、次のようにしてください。

大きなバッチは、1 回のバッチ呼び出しにつき約 25～30 件に分割します。 バッチが途中で 429 エラーにより失敗した場合は、未処理の操作だけを再実行します。 batch の出力には、失敗前に成功した操作が表示されます。index フィールドを使って、どこから再開するかを判断してください。

出力形式

JSON（デフォルト）

すべてのコマンドは、AI が扱いやすいよう、デフォルトで JSON を出力します。

{
  "id": "...",
  "object": "page",
  "properties": { ... }
}

Pretty（人間が読みやすい形式）

整形された出力には --pretty フラグを使用します。

vibe-notionbot search "Project" --pretty

エラー処理

Notion API でよく発生するエラー：

• object_not_found：ID が正しくないか、インテグレーションにアクセス権がありません。
• unauthorized：NOTION_TOKEN が無効です。
• rate_limited：リクエストが多すぎます。

トラブルシューティング

vibe-notionbot: command not found

vibe-notion パッケージがインストールされていません。パッケージランナーを使って直接実行してください。どのランナーを使うか、ユーザーに確認します。

npx -y -p vibe-notion vibe-notionbot ...
bunx -p vibe-notion vibe-notionbot ...
pnpm dlx --package vibe-notion vibe-notionbot ...

ユーザーが使うパッケージランナーをすでに把握している場合は、確認せずにそれを直接使用してください。

制限事項

• Notion API バージョン 2025-09-03 をサポートしています。
• OAuth はサポートしていません（トークンのみ）。
• ファイルのアップロードは block upload でサポートされています。
• ページプロパティの更新は、--set による単純な key=value ペアに限定されます。