notion-cli

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

# Or download a binary from https://github.com/4ier/notion-cli/releases

認証

notion auth login --with-token <<< "ntn_xxxxxxxxxxxxx"
notion auth login --with-token --profile work <<< "ntn_xxx"  # named profile
export NOTION_TOKEN=ntn_xxxxxxxxxxxxx                        # env var alternative
notion auth status        # shows workspace + integration type (internal/public)
notion auth switch        # interactive profile picker
notion auth switch work   # direct switch
notion auth doctor        # health check — warns if internal integration

auth status / doctor にはインテグレーションの種類が表示されるため、ワークスペースのルートにコンテンツを作成する前に親ページを共有する必要があるかどうかを簡単に確認できます。

検索

notion search "query"                    # everything
notion search "query" --type page        # pages only
notion search "query" --type database    # databases only

ページ

notion page view <id|url>                # render page content
notion page list                         # list workspace pages
notion page create <parent> --title "X" --body "content"
notion page create <db-id> --db "Name=Review" "Status=Todo"  # database row

# Archive / restore (soft-delete)
notion page archive <id>                 # canonical
notion page trash <id>                   # alias
notion page delete <id>                  # alias (legacy)
notion page restore <id>                 # reverse

# Move / open / edit
notion page move <id> --to <parent>
notion page open <id>                    # open in browser
notion page edit <id|url>                # edit in $EDITOR (markdown round-trip)

# Properties (type-aware)
notion page set <id> Key=Value ...
notion page props <id>                   # show all (summary; paginated values may be truncated)
notion page props <id> <prop-id>         # single raw JSON

# NEW in v0.7: paginated single-property fetch (fixes >25-item truncation)
notion page property <id> <prop-id>
notion page property <id> --name "References"         # resolve id by display name
notion page property <id> <prop-id> --format json

# Relations
notion page link <id> --prop "Rel" --to <target-id>
notion page unlink <id> --prop "Rel" --from <target-id>

# NEW in v0.7: server-side markdown I/O (preferred for full-page dumps)
notion page markdown <id>                # print to stdout
notion page markdown <id> --out page.md  # write to file
notion page markdown <id> --format json  # full response (truncated flag, unknown_block_ids)

notion page set-markdown <id> --file new.md           # replace whole page (default)
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 と block list --md の違い：ページ全体を扱う場合は、page markdown を推奨します。サーバー側のレンダラーを使用し、トグル、カラム、同期ブロック、ページとしてのデータベースを正しく処理します。単一のサブブロックが必要な場合にのみ、block list --md を使用してください。

データベース

notion db list                           # list databases
notion db view <id>                      # show schema
notion db query <id>                     # all rows
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 (default)
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>            # list child blocks
notion block list <parent-id> --all
notion block list <parent-id> --depth 3  # recursive
notion block list <parent-id> --md       # markdown; prefer 'page markdown' for pages
notion block get <id>

# Append / insert — both handle >100 children and >2000-char code blocks automatically
notion block append <parent> "text"
notion block append <parent> "text" -t bullet
notion block append <parent> "text" -t code --lang ts        # 'ts' / 'sh' / 'yml' etc. normalized
notion block append <parent> --file notes.md                 # any length, auto-batched
notion block append <parent> --file big.md --on-oversize=truncate
notion block insert <parent> "text" --after <block-id>

# Update — now with markdown support
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                     # must parse to exactly one block

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）

# External URL (http/https)
notion block append <page> --image-url https://example.com/a.png --caption "fig 1"

# Local file → upload + embed in one command
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

# Reference an existing file_upload id
notion block append <page> --image-upload 351d45fb-... --caption "reused"

image、file、video、audio、pdf には、同じ3種類（--<kind>-url / --<kind>-file / --<kind>-upload）が用意されています。--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"          # same thread

# NEW in 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>                      # single or many
notion comment delete <id1> <id2> <id3>                 # variadic

ユーザー

notion user me                           # current bot info
notion user list                         # all workspace users
notion user get <user-id>

ファイル

# List / retrieve / upload
notion file list
notion file get <upload-id>                                # NEW in v0.7 — status / size / URL
notion file upload ./local/file.pdf                        # local path
notion file upload https://example.com/chart.png --name chart.png   # URL source
curl -sSL https://host/file.zip | notion file upload - --name file.zip   # stdin
notion file upload ./image.png --to <page-id>              # upload + attach to page

Raw API（緊急用）

notion api GET /v1/users/me              # /v1/ is auto-prepended if missing
notion api GET /users/me                 # → prints 'note: prepending /v1...' and works
notion api POST /v1/search --body '{"query":"test"}'
notion api PATCH /v1/pages/<id> --body @body.json        # read body from file
echo '{"query":"x"}' | notion api POST /v1/search --body -  # explicit 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 プロパティには、必ず page view / page props ではなく notion page property を使用してください。
• jq にパイプで渡せます：notion db query <id> -F 'Status=Done' --format json | jq '.results[].id'
• エラーが分かりにくい場合は、→ のヒント行があるか確認してください。CLI は、よくある API エラーに実行可能な次の手順を付け加えます。
• 内部インテグレーションを使用する場合、ワークスペースのルートへのページ作成は許可されていません。先に親ページを共有してから、その ID を渡してください。