notion

Notion CLI

Notion のリモート MCP サーバーを使用して、コマンドラインから Notion を管理する CLI です。

前提条件

notion-cli コマンドが PATH 上で利用可能である必要があります。確認するには、次を実行します。

notion-cli version

インストールされていない場合：

go install github.com/lox/notion-cli@latest

または、こちらをご覧ください：https://github.com/lox/notion-cli

認証

CLI は MCP を利用するコマンドで OAuth 認証を使用します。初回使用時には、認証のためにブラウザーが開きます。

notion-cli auth login      # Authenticate with Notion
notion-cli auth status     # Show active profile and OAuth state (diagnostic)
notion-cli auth refresh    # Force-refresh; commands auto-refresh on use, so rarely needed
notion-cli auth logout     # Clear credentials

CI／ヘッドレス環境では、NOTION_ACCESS_TOKEN 環境変数を設定してください。

一部のフォールバック機能では、公式 Notion API も使用します。

notion-cli auth api setup
notion-cli auth api status
notion-cli auth api verify
notion-cli auth api unset

CI／ヘッドレス環境では、NOTION_API_TOKEN を設定してください。

複数アカウント

すべてのコマンドで --profile <name>（または NOTION_CLI_PROFILE）を指定して、対象の Notion アカウントを選択できます。名前付きプロファイルは、認証情報を ~/.config/notion-cli/profiles/<profile>/ 以下に分離して保存します。暗黙的なデフォルトプロファイルでは、既存のトップレベルパスが使用されます。

notion-cli auth login --profile work
notion-cli page list --profile work
export NOTION_CLI_PROFILE=work  # pin for the shell session
notion-cli auth use work         # make work the default profile

優先順位：--profile > NOTION_CLI_PROFILE > notion-cli auth use <name> > 暗黙的なデフォルトプロファイル。

利用可能なコマンド

notion-cli auth            # Manage authentication
notion-cli page            # Manage pages (list, view, create, upload, edit)
notion-cli db              # Manage databases (list, query, create entries)
notion-cli search          # Search the workspace
notion-cli comment         # Manage comments (list, create)
notion-cli tools           # List available MCP tools

よく使う操作

検索

notion-cli search "meeting notes"           # Search workspace
notion-cli search "project" --limit 5       # Limit results
notion-cli search "query" --json            # JSON output

ページ

すべてのページコマンドでは、ページを特定するために URL、名前、または ID を指定できます。

# List pages
notion-cli page list
notion-cli page list --limit 10
notion-cli page list --json

# View a page (renders as markdown in terminal)
notion-cli page view <page>
notion-cli page view <page> --no-comments    # Hide page and block comments
notion-cli page view <page> --raw            # Show raw Notion markup
notion-cli page view <page> --json           # JSON output
notion-cli page view "Meeting Notes"         # By name
notion-cli page view https://notion.so/...   # By URL

# Create a page
notion-cli page create --title "New Page"
notion-cli page create --title "Doc" --content "# Heading\n\nContent here"
notion-cli page create --title "Child" --parent "Engineering"   # Parent by name
notion-cli page create --title "Child" --parent <page-id>       # Parent by ID

# Upload a markdown file as a page
notion-cli page upload ./document.md
notion-cli page upload ./doc.md --title "Custom Title"
notion-cli page upload ./doc.md --parent "Parent Page Name"
notion-cli page upload ./doc.md --parent-db <db-id>         # Upload as database entry

# Sync a markdown file (create or update)
# First run creates the page and writes notion-id to the file's frontmatter.
# Subsequent runs update the page content using the stored notion-id.
notion-cli page sync ./document.md
notion-cli page sync ./document.md --parent "Engineering"   # Set parent on first sync
notion-cli page sync ./document.md --parent-db <db-id>      # Sync as database entry
notion-cli page sync ./document.md --title "Custom Title"

# Edit a page
notion-cli page edit <page> --replace "New content"
notion-cli page edit <page> --find "old text" --replace-with "new text"
notion-cli page edit <page> --find "section" --append "additional content"

# Archive a page
notion-cli page archive https://notion.so/...
notion-cli page archive 12345678-abcd-ef12-3456-7890abcdef12

page upload と page sync では、単独行のローカル Markdown 画像構文（例：![Alt](./diagram.png)）は、設定済みの場合、公式 API 経由でネイティブにアップロードされます。ローカル画像は単独の行に記述する必要があります。インライン形式や、ほかのコンテンツと混在したローカル画像構文は拒否されます。

page view は、デフォルトでページレベルの未解決コメントとインラインのブロックディスカッションを表示します。インラインディスカッションはアンカーテキストの横に表示され、アンカーテキストは [[...]] で囲まれ、ディスカッションはその直下に表示されます。ページ本文のみが必要な場合は --no-comments を、元の Notion マークアップを確認する場合は --raw を、エージェントがページと Comments 配列を必要とする場合は --json を使用してください。

page archive は公式 API のフォールバック経路を使用するため、notion-cli auth api setup または NOTION_API_TOKEN が必要です。

編集モードのガードレール

page edit は、相互排他的な次のモードをサポートします。

1. ページ全体を置き換えるには --replace "..." を指定します。
2. 対象を絞って置き換えるには --find "..." --replace-with "..." を指定します。
3. 一致箇所の後に追記するには --find "..." --append "..." を指定します。

対象を絞った編集に失敗した場合（MCP の検証エラーなど）は、コンテンツを取得してローカルで編集した後、--replace を適用してページ全体を置き換えてください。

データベース

すべてのデータベースコマンドでは、データベースを特定するために URL、名前、または ID を指定できます。

# List databases
notion-cli db list                          # List databases
notion-cli db list -q "project"             # Filter by name
notion-cli db list --json

# Query a database
notion-cli db query <database-url-or-id>    # Query a database
notion-cli db query <id> --json

# Create an entry in a database
notion-cli db create <database> --title "Entry Title"
notion-cli db create <database> -t "Title" --prop "Status=Not started"
notion-cli db create <database> -t "Title" --prop "date:Due:start=2026-03-01"
notion-cli db create <database> -t "Title" --content "Body text"
notion-cli db create <database> -t "Title" --file ./notes.md    # Body from file
notion-cli db create <database> -t "Title" --json

プロパティの形式： テキスト／ステータスのプロパティには --prop Key=Value を使用します。日付プロパティでは、展開形式のキーを使用します：--prop "date:Date Field:start=2026-01-15"。

コメント

notion-cli comment list <page>              # List open page and block comments
notion-cli comment list <page> --resolved   # Include resolved discussions too
notion-cli comment list <page> --json
notion-cli comment list "Meeting Notes"     # Resolve a page by name

notion-cli comment create <page> --content "Great work!"
notion-cli comment create https://notion.so/... --content "Looks good"

コメントコマンドでは、ページの URL、ID、または名前を指定できます。comment list はデフォルトでページレベルとブロックレベルの両方のディスカッションを含み、--resolved を指定しない限り、未解決のディスカッションのみを表示します。

出力形式

ほとんどのコマンドは、機械可読な出力を得るための --json をサポートしています。

notion-cli page list --json | jq '.[0].url'
notion-cli search "api" --json | jq '.[] | .title'

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

1. まず検索する - ページを操作する前に、notion-cli search を使ってページを検索します
2. URL、名前、または ID を使う - すべてのページコマンドとコメントコマンドでは、これらの形式からページを解決できます
3. 親の種類を明示する - page sync／page upload では、ページを親にする場合は --parent、データベースを親にする場合は --parent-db を使います
4. まずデータベースをクエリする - エントリーを作成する前に、notion-cli db query <id> を使ってスキーマとプロパティの種類を確認します
5. --help を確認する - 各コマンドには詳細なヘルプがあります：notion-cli page edit --help
6. インラインコメントがデフォルト - page view には、未解決のページコメントとインラインのブロックディスカッションが含まれます。--no-comments を指定すると含まれません
7. 生の出力 - --raw を page view と併用すると、元の Notion マークアップを確認できます
8. 解析には JSON を使う - page view の Comments 配列など、特定のフィールドを抽出する必要がある場合は --json を使います
9. 事前の認証チェックは不要 - コマンドを実行してください。CLI は使用時にトークンを自動更新します。notion-cli auth status と notion-cli auth list は診断用であり、ヘルスチェック用ではありません。各呼び出しの前に健全性確認として繰り返し実行しないでください。実際のコマンドが認証エラーを返した場合にのみ、notion-cli auth login を実行します
10. API フォールバックの事前チェック - ローカル画像のアップロードが必要なワークフローを実行する前に、notion-cli auth api verify を実行します
11. エラー処理 - 対象を指定した page edit 呼び出しが失敗した場合は、安全なフォールバックとして --replace を指定して再実行します