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，如果已配置官方 API，独立成行的本地 Markdown 图片语法（如 ![Alt](./diagram.png)）会通过该 API 原生上传。本地图片必须单独成行。不支持行内或混合内容中的本地图片语法。

默认情况下，page view 会显示页面级未解决评论和行内块讨论。行内讨论会显示在其锚点文本旁边，锚点文本用 [[...]] 包裹，讨论则紧接其下方显示。仅需要页面正文时使用 --no-comments；要检查原始 Notion 标记时使用 --raw；Agent 需要页面及其 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'

给 Agent 的提示

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. 默认包含行内评论 - 除非设置了 --no-comments，否则 page view 会包含未解决的页面评论和行内区块讨论
7. 原始输出 - 使用 page view 时添加 --raw，查看原始 Notion 标记
8. 使用 JSON 进行解析 - 需要提取特定字段时使用 --json，包括 page view 中的 Comments 数组
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 重新运行，作为安全回退