notion-cli

Notion CLI

4ier/notion-cli Go バイナリを介して、Notion に高速かつエージェントフレンドリーにアクセスできます。単一の静的バイナリで、起動は 1 秒未満、パイプに渡すと JSON に自動変換されます。

自己進化型スキル：指示にずれが生じた場合は、このファイルをすぐに修正してください。先送りしないでください。

使用するタイミング

ユーザーがコマンドラインから Notion を操作したい場合（ページの検索、データベースのクエリ、コンテンツの読み取り、データのエクスポート、ブロックの管理、コメントの追加など）に、このスキルを使用してください。Go バイナリの notion をラップしています（brew install 4ier/tap/notion-cli でインストール）。

Notion SDK を使った Python によるプログラムでの自動化には、このスキルを使用しないでください。代わりに productivity-tools:notion-sdk を使用してください。このスキルは、CLI を優先するパイプ対応の操作向けです。

事前確認

操作を行う前に、CLI が認証済みであることを確認してください。

notion auth status

認証されていない場合は、Doppler からトークンを取得して認証してください。

doppler secrets get NOTION_API_TOKEN --project private-config --config prd --plain | notion auth login --with-token

代替手段：ユーザーにインテグレーショントークンを尋ねてください。

出力形式

CLI はコンテキストを自動検出します。

• TTY（対話型ターミナル）：色付きテーブル
• パイプ経由（jq、ファイルなど）：整形済み JSON

--format で形式を指定できます。

フラグ	出力
--format json	JSON
--format table	ASCII テーブル
--format md	Markdown
--format text	プレーンテキスト

エージェントで利用する場合は、構造化された出力を得るため、必ずパイプに渡すか --format json を使用してください。

主なコマンド

検索

notion search "meeting notes"                  # Search by title
notion search --type page "roadmap"            # Pages only
notion search --type database                  # List all databases
notion search --all                            # Fetch all results (paginated)
notion search --limit 20 "query"               # Limit results

ページ

notion page view <page-id|url>                 # View page content (blocks as markdown)
notion page props <page-id|url>                # Show page properties
notion page create --parent <id> --title "X"   # Create a page
notion page set <id> --prop 'Status=Done'      # Set property
notion page edit <id>                          # Edit in $EDITOR
notion page move <id> --to <parent-id>         # Move page
notion page delete <id>                        # Archive page
notion page restore <id>                       # Restore archived page
notion page open <id>                          # Open in browser
notion page list                               # List accessible pages

データベース

notion db list                                 # List all databases
notion db view <db-id|url>                     # Show schema
notion db query <db-id|url>                    # Query all rows
notion db query <id> --filter 'Status=Done'    # Simple filter
notion db query <id> --filter 'Date>=2026-01-01' --sort 'Date:desc'
notion db query <id> --filter-json '{"or":[...]}' # Complex filters
notion db query <id> --all                     # Fetch all pages
notion db export <id> --format csv -o data.csv # Export to CSV
notion db export <id> --format json            # Export to JSON
notion db export <id> --format md              # Export to Markdown table
notion db add <id> --prop 'Name=Task' --prop 'Status=Todo'  # Add row
notion db add-bulk <id> --file rows.json       # Bulk add from JSON

フィルター演算子：= != > >= < <= ~=（含む）

複数の --filter フラグは AND 条件として結合されます。OR 条件には --filter-json を使用してください。

ブロック

notion block list <page-id|url>                # List child blocks
notion block list <id> --depth 3               # Recursive (3 levels)
notion block get <block-id>                    # Get specific block
notion block append <page-id> --md "# Hello"   # Append markdown
notion block insert <after-block-id> --md "X"  # Insert after block
notion block delete <block-id>                 # Delete block
notion block move <block-id> --to <parent-id>  # Move block

コメント

notion comment list <page-id>                  # List comments
notion comment add <page-id> --body "text"     # Add comment
notion comment reply <comment-id> --body "X"   # Reply to comment

ユーザー

notion user me                                 # Current bot user
notion user list                               # Workspace users
notion user get <user-id>                      # User details

ファイル

notion file upload <file-path>                 # Upload file
notion file list                               # List uploads

Raw API（回避策）

notion api GET /v1/users/me
notion api POST /v1/search --body '{"query":"test"}'
echo '{"query":"test"}' | notion api POST /v1/search

ID の解決

CLI は Notion の URL と生の ID のどちらも同様に受け付けます。

notion page view https://www.notion.so/My-Page-abc123def456
notion page view abc123def456

よくあるパターン

データベース全体を JSON にエクスポートする

notion db export <db-id> --format json -o database.json

検索結果を jq にパイプで渡す

notion search "project" --format json | jq '.results[] | {title: .properties.title.title[0].plain_text, url: .url}'

すべてのデータベースを ID とともに一覧表示する

notion search --type database --all --format json | jq '.results[] | {id: .id, title: .title[0].plain_text}'

ページコンテンツを再帰的にダンプする

notion block list <page-id> --depth 10 --format md

認証情報の保存先

保存先	場所	用途
Doppler	private-config/prd:NOTION_API_TOKEN	トークンの SSoT
CLI	~/.config/notion/credentials.json	ローカル認証キャッシュ

トークン形式：ntn_*（Notion 内部インテグレーショントークン）。

トラブルシューティング

問題	対処方法
unauthorized	トークンの期限切れまたは取り消しです。notion.so/profile/integrations で再生成してください
object not found	ページがインテグレーションに接続されていません。ページメニュー > Connections から追加してください
rate_limited	CLI は自動的に再試行します。一括操作では --limit を使ってバッチサイズを減らしてください
validation_error	プロパティ名がスキーマと一致しているか確認してください：notion db view <id>

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ 成功しなかった場合は、失敗の原因となった指示またはエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ CLI のインターフェースにずれが生じていた場合は、使用例とコマンドテーブルを更新してください。
3. 回避策が必要でしたか？ 別のフラグや追加手順など、工夫が必要だった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

問題が実際に発生し再現可能な場合にのみ更新してください。推測に基づく更新はしないでください。