Notion CLI

notion は Notion API 用の CLI です。単一の Go バイナリ、完全な API カバレッジ、デュアル出力（人間向けの見やすいテーブル、エージェント向けの JSON）。現在バージョン: v0.7.0。

インストール

# Homebrew
brew install 4ier/tap/notion-cli

# npm
npm install -g @4ier/notion-cli

# Go
go install github.com/4ier/notion-cli@latest

# または https://github.com/4ier/notion-cli/releases からバイナリをダウンロード

認証

notion auth login --with-token <<< "ntn_xxxxxxxxxxxxx"
notion auth login --with-token --profile work <<< "ntn_xxx"  # 名前付きプロフィール
export NOTION_TOKEN=ntn_xxxxxxxxxxxxx                        # 環境変数による方法
notion auth status        # ワークスペース + インテグレーションタイプを表示（内部/公開）
notion auth switch        # インタラクティブなプロフィールピッカー
notion auth switch work   # 直接切り替え
notion auth doctor        # ヘルスチェック — 内部インテグレーションの場合は警告

auth status / doctor はインテグレーションタイプを表示するため、ワークスペースルートのコンテンツを作成する前に親ページを共有する必要がある場合を簡単に判断できます。

検索

notion search "query"                    # すべて
notion search "query" --type page        # ページのみ
notion search "query" --type database    # データベースのみ

ページ

notion page view <id|url>                # ページコンテンツを表示
notion page list                         # ワークスペースページを一覧表示
notion page create <parent> --title "X" --body "content"
notion page create <db-id> --db "Name=Review" "Status=Todo"  # データベース行

# アーカイブ / 復元（ソフト削除）
notion page archive <id>                 # 標準
notion page trash <id>                   # エイリアス
notion page delete <id>                  # エイリアス（レガシー）
notion page restore <id>                 # 逆操作

# 移動 / 開く / 編集
notion page move <id> --to <parent>
notion page open <id>                    # ブラウザで開く
notion page edit <id|url>                # $EDITOR で編集（markdown ラウンドトリップ）

# プロパティ（タイプに対応）
notion page set <id> Key=Value ...
notion page props <id>                   # すべてを表示（サマリー；ページネーション値は切り詰められる可能性がある）
notion page props <id> <prop-id>         # 単一の生 JSON

# v0.7 の新機能: ページネーション付き単一プロパティ取得（>25 アイテムの切り詰めを修正）
notion page property <id> <prop-id>
notion page property <id> --name "References"         # 表示名で ID を解決
notion page property <id> <prop-id> --format json

# リレーション
notion page link <id> --prop "Rel" --to <target-id>
notion page unlink <id> --prop "Rel" --from <target-id>

# v0.7 の新機能: サーバーサイド markdown I/O（ページ全体ダンプに推奨）
notion page markdown <id>                # stdout に出力
notion page markdown <id> --out page.md  # ファイルに書き込み
notion page markdown <id> --format json  # 完全なレスポンス（truncated フラグ、unknown_block_ids）

notion page set-markdown <id> --file new.md           # ページ全体を置き換え（デフォルト）
cat new.md | notion page set-markdown <id> --file -   # stdin
notion page set-markdown <id> --append --text "\n\n> Appended"
notion page set-markdown <id> --after "Status...pending" --text "Now: done"
notion page set-markdown <id> --range "old...stale" --text "fresh" --allow-deleting-content

page markdown vs block list --md: ページ全体には page markdown を使用することをお勧めします。サーバーレンダラーを使用し、トグル、列、同期ブロック、およびデータベース形式のページを正しく処理します。単一のサブブロックが必要な場合のみ block list --md を使用します。

データベース

notion db list                           # データベースを一覧表示
notion db view <id>                      # スキーマを表示
notion db query <id>                     # すべての行
notion db query <id> -F 'Status=Done' -s 'Date:desc'
notion db query <id> --filter-json '{"or":[...]}'
notion db query <id> --all
notion db create <parent> --title "X" --props "Status:select,Date:date"
notion db update <id> --title "New Name" --add-prop "Priority:select"
notion db add <id> "Name=Task" "Status=Todo" "Priority=High"
notion db add-bulk <id> --file items.json
notion db export <id>                    # CSV（デフォルト）
notion db export <id> --format json
notion db export <id> --format md -o report.md
notion db open <id>

フィルター演算子

構文	意味
=	等しい
!=	等しくない
> / >=	より大きい（または等しい）
< / <=	より小さい（または等しい）
~=	含む

複数の -F フラグは AND で組み合わされます。プロパティタイプはスキーマから自動検出されます。

ソート: -s 'Date:desc' または -s 'Name:asc'

一括追加ファイルフォーマット

[{"Name": "Task A", "Status": "Todo"}, {"Name": "Task B", "Status": "Done"}]

ブロック

notion block list <parent-id>            # 子ブロックを一覧表示
notion block list <parent-id> --all
notion block list <parent-id> --depth 3  # 再帰的
notion block list <parent-id> --md       # markdown；ページの場合は 'page markdown' を推奨
notion block get <id>

# 追加 / 挿入 — >100 子と >2000 文字のコードブロックを自動的に処理
notion block append <parent> "text"
notion block append <parent> "text" -t bullet
notion block append <parent> "text" -t code --lang ts        # 'ts' / 'sh' / 'yml' など正規化
notion block append <parent> --file notes.md                 # 任意の長さ、自動バッチ処理
notion block append <parent> --file big.md --on-oversize=truncate
notion block insert <parent> "text" --after <block-id>

# 更新 — 現在 markdown サポート付き
notion block update <id> --text "plain new content"
notion block update <id> --text "See **[docs](https://x.com)**" --markdown
notion block update <id> --file patch.md                     # 正確に 1 つのブロックに解析する必要あり

notion block delete <id1> [id2] [id3]
notion block move <id> --after <target>
notion block move <id> --before <target>
notion block move <id> --parent <new-parent>

ブロックタイプ: paragraph/p、h1/h2/h3、bullet、numbered、todo、quote、code、callout、divider。

メディアブロック（画像 / ファイル / ビデオ / オーディオ / PDF）

# 外部 URL（http/https）
notion block append <page> --image-url https://example.com/a.png --caption "fig 1"

# ローカルファイル → アップロード + 1 つのコマンドで埋め込み
notion block append <page> --image-file ./chart.png --caption "heap usage"
notion block append <page> --pdf-file ./spec.pdf
notion block append <page> --video-file ./demo.mp4

# 既存の file_upload ID を参照
notion block append <page> --image-upload 351d45fb-... --caption "reused"

同じトリプル（--<kind>-url / --<kind>-file / --<kind>-upload）は image、file、video、audio、pdf に存在します。--caption はすべてで機能します。

コメント

notion comment list <page-id>
notion comment add <page-id> --text "comment text"
notion comment add <page-id> --text "with @mention" --mention-user <user-id>
notion comment get <comment-id>
notion comment reply <comment-id> "reply text"          # 同じスレッド

# v0.7 の新機能
notion comment update <comment-id> --text "edited text"
notion comment update <comment-id> --text "with @mention" --mention-user <user-id>
notion comment delete <comment-id>                      # 単一または複数
notion comment delete <id1> <id2> <id3>                 # 可変長引数

ユーザー

notion user me                           # 現在のボット情報
notion user list                         # すべてのワークスペースユーザー
notion user get <user-id>

ファイル

# 一覧表示 / 取得 / アップロード
notion file list
notion file get <upload-id>                                # v0.7 の新機能 — ステータス / サイズ / URL
notion file upload ./local/file.pdf                        # ローカルパス
notion file upload https://example.com/chart.png --name chart.png   # URL ソース
curl -sSL https://host/file.zip | notion file upload - --name file.zip   # stdin
notion file upload ./image.png --to <page-id>              # アップロード + ページにアタッチ

Raw API（エスケープハッチ）

notion api GET /v1/users/me              # /v1/ は見つからない場合は自動的に前置き
notion api GET /users/me                 # → '/v1...' を前置きして機能するというメモを表示
notion api POST /v1/search --body '{"query":"test"}'
notion api PATCH /v1/pages/<id> --body @body.json        # ファイルからボディを読み込み
echo '{"query":"x"}' | notion api POST /v1/search --body -  # 明示的な stdin

出力モード

• ターミナル（TTY）: 色付きテーブル、読みやすい形式
• パイプ / スクリプト: JSON が自動的に出力
• 明示的な指定: --format json / --format table / --format md
• --debug: HTTP リクエスト/レスポンスの詳細を表示

すべての出力に完全な Notion UUID が含まれます。すべてのコマンドが Notion URL または ID を受け入れます。

エージェント向けのヒント

• notion db add と notion page set はスキーマからプロパティタイプを自動検出するため、Tags=a,b,c（multi_select）と Done=true（checkbox）の両方がそのまま機能します。
• 長い markdown の場合、notion block append --file ではなく notion page set-markdown --file を推奨します — サーバーサイド解析には 100 子の制限がありません。
• 25 個以上のアイテムを持つ可能性がある relation / rollup プロパティについては、常に notion page property を使用します（page view / page props ではなく）。
• jq にパイプ: notion db query <id> -F 'Status=Done' --format json | jq '.results[].id'
• エラーが紛らわしく見える場合は、→ ヒント行がないか確認してください — CLI は一般的な API エラーを実行可能な次のステップで装飾します。
• 内部インテグレーションを操作する場合: ワークスペースルートページの作成は許可されていません — 最初に親ページを共有してから、その ID を渡します。