notion（Notion 知识协作）

Notion CLI Skill

Operate Notion workspaces using ncli. Two backends:

• MCP (OAuth) — search, pages, databases, views, comments, users, teams
• REST API (integration token) — file upload, block operations, any REST endpoint

Prerequisites

# MCP auth (required for most commands)
ncli whoami                    # Check auth status
ncli login                     # If not authenticated

# REST API auth (required for ncli rest / ncli file commands)
ncli rest login                # Save integration token (one-time)

REST API requires integration access to target pages: Go to https://www.notion.so/profile/integrations/internal → select your integration → Content access → add pages.

Core Pattern: Search → Fetch → Act

1. Search — ncli search "<query>" --json to find pages/databases
2. Fetch — ncli fetch <id> --json to get details and extract IDs
3. Act — Use the extracted IDs to create/update/query

See references/id-patterns.md for ID extraction patterns.

Key Commands

MCP Commands (OAuth)

REST API Commands (Integration Token)

See references/command-reference.md for full arguments and examples.

Global Flags

• --json — Structured JSON output (always use for programmatic access)
• --raw — Raw response
• --data '{json}' — Override all flags with direct JSON input

Common Workflows

1. Search, Fetch, and Update

ncli search "project plan" --json       # → results[].id
ncli fetch <page-id> --json             # → content
ncli page update <page-id> --prop "Status=Done"

2. Database Lifecycle

# Create DB → extract data_source_id (collection://...) from response
ncli db create --title "Tasks" --parent <page-id> \
  --prop "Name:title" --prop "Status:select=Open,Done"

# Create view → extract view_url
ncli view create --data '{"database_id":"<db-id>","data_source_id":"collection://<ds-id>","type":"table","name":"All"}'

# Add entries
ncli page create --parent collection://<ds-id> --title "Task 1" --prop "Status=Open"

# Query
ncli db query "<view-url>"

3. File Upload (REST API)

# Step 1: Upload file → returns file_upload_id + attach hint
ncli file upload ./screenshot.png

# Step 2: Fetch page to find block IDs (MCP or REST)
ncli fetch <page-id> --json
# Or: ncli rest GET /blocks/<page-id>/children

# Step 3: Attach to page (append to end)
ncli rest PATCH /blocks/<page-id>/children '{"children":[{"type":"file","file":{"type":"file_upload","file_upload":{"id":"<file_upload_id>"},"name":"screenshot.png"}}]}'

# Or: Insert after a specific block
ncli rest PATCH /blocks/<page-id>/children '{"position":{"type":"after_block","after_block":{"id":"<block-id>"}},"children":[...]}'

4. Direct REST API Access

ncli rest GET /users/me                 # Verify auth
ncli rest GET /pages/<page-id>          # Get page
ncli rest POST /search '{"query":"x"}'  # Search
ncli rest PATCH /blocks/<id>/children '{"children":[...]}' # Add blocks

Important Notes

1. page update: properties and content are separate commands — --prop/--title and --body cannot be combined
2. db query requires a view URL — run ncli fetch <db-id> to get it, or create one with ncli view create
3. view create requires both database_id AND data_source_id — get both from ncli fetch <db-id>
4. DB page parent uses collection:// prefix — --parent collection://<ds-id>
5. ncli file upload returns file_upload_id — attach to page via ncli rest PATCH (the command prints the exact attach command)
6. REST API requires separate auth from MCP — ncli rest login or NOTION_API_KEY env var
7. REST API requires page access — add pages via integration settings at https://www.notion.so/profile/integrations/internal
8. Errors include recovery hints — follow the Hint to self-recover

Troubleshooting

MCP auth failed

Error: Not connected to Notion

Run ncli login to authenticate via browser.

REST API: No token

Error: No REST API token configured
  Hint: Set NOTION_API_KEY env var, or run "ncli rest login"

Run ncli rest login or set NOTION_API_KEY.

REST API: Empty search results

Note: No results found. If you expected results, ensure your integration has access to pages.

Go to https://www.notion.so/profile/integrations/internal → select integration → Content access → add pages.

REST API: 404 on page access

Error: REST API resource not found
  Hint: The integration may not have access to this page.

The integration needs explicit access to the page. Add it via integration settings, or use MCP commands which have workspace-wide OAuth access.

File upload: attach fails

If ncli file upload succeeds but ncli rest PATCH to attach fails with 404, the integration doesn't have access to the target page. Add access via integration settings.