notion-cli

Notion CLI

通过 4ier/notion-cli Go 二进制文件快速、便于 Agent 地访问 Notion。单个静态二进制文件，启动时间不到 1 秒，管道传输时自动输出 JSON。

自我演进的技能：如果说明与实际情况不符，请立即修复此文件。不要拖延。

何时使用

当用户希望通过命令行与 Notion 交互时，使用此技能——例如搜索页面、查询数据库、阅读内容、导出数据、管理区块或添加评论。此技能封装了 Go 二进制文件 notion（通过 brew install 4ier/tap/notion-cli 安装）。

对于使用 Notion SDK 进行 Python 编程自动化，请勿使用此技能——请改用 productivity-tools:notion-sdk。此技能适用于以 CLI 为主、便于管道传输的操作。

预检

执行任何操作之前，请确认 CLI 已完成身份验证：

notion auth status

如果尚未完成身份验证，请从 Doppler 获取令牌并进行身份验证：

doppler secrets get NOTION_API_TOKEN --project private-config --config prd --plain | notion auth login --with-token

备用方案：请用户提供其集成令牌。

输出格式

CLI 会自动检测上下文：

• TTY（交互式终端）：彩色表格
• 管道传输（传给 jq、文件等）：纯净的 JSON

使用 --format 指定格式：

标志	输出
--format json	JSON
--format table	ASCII 表格
--format md	Markdown
--format text	纯文本

供 Agent 使用时，始终通过管道传输或使用 --format json 获取结构化输出。

核心命令

搜索

notion search "meeting notes"                  # Search by title
notion search --type page "roadmap"            # Pages only
notion search --type database                  # List all databases
notion search --all                            # Fetch all results (paginated)
notion search --limit 20 "query"               # Limit results

页面

notion page view <page-id|url>                 # View page content (blocks as markdown)
notion page props <page-id|url>                # Show page properties
notion page create --parent <id> --title "X"   # Create a page
notion page set <id> --prop 'Status=Done'      # Set property
notion page edit <id>                          # Edit in $EDITOR
notion page move <id> --to <parent-id>         # Move page
notion page delete <id>                        # Archive page
notion page restore <id>                       # Restore archived page
notion page open <id>                          # Open in browser
notion page list                               # List accessible pages

数据库

notion db list                                 # List all databases
notion db view <db-id|url>                     # Show schema
notion db query <db-id|url>                    # Query all rows
notion db query <id> --filter 'Status=Done'    # Simple filter
notion db query <id> --filter 'Date>=2026-01-01' --sort 'Date:desc'
notion db query <id> --filter-json '{"or":[...]}' # Complex filters
notion db query <id> --all                     # Fetch all pages
notion db export <id> --format csv -o data.csv # Export to CSV
notion db export <id> --format json            # Export to JSON
notion db export <id> --format md              # Export to Markdown table
notion db add <id> --prop 'Name=Task' --prop 'Status=Todo'  # Add row
notion db add-bulk <id> --file rows.json       # Bulk add from JSON

筛选运算符：= != > >= < <= ~=（包含）

多个 --filter 标志会以 AND 方式组合。对于 OR 逻辑，请使用 --filter-json。

区块

notion block list <page-id|url>                # List child blocks
notion block list <id> --depth 3               # Recursive (3 levels)
notion block get <block-id>                    # Get specific block
notion block append <page-id> --md "# Hello"   # Append markdown
notion block insert <after-block-id> --md "X"  # Insert after block
notion block delete <block-id>                 # Delete block
notion block move <block-id> --to <parent-id>  # Move block

评论

notion comment list <page-id>                  # List comments
notion comment add <page-id> --body "text"     # Add comment
notion comment reply <comment-id> --body "X"   # Reply to comment

用户

notion user me                                 # Current bot user
notion user list                               # Workspace users
notion user get <user-id>                      # User details

文件

notion file upload <file-path>                 # Upload file
notion file list                               # List uploads

原始 API（备用方案）

notion api GET /v1/users/me
notion api POST /v1/search --body '{"query":"test"}'
echo '{"query":"test"}' | notion api POST /v1/search

ID 解析

CLI 可以互换接受 Notion URL 和原始 ID：

notion page view https://www.notion.so/My-Page-abc123def456
notion page view abc123def456

常见模式

将整个数据库导出为 JSON

notion db export <db-id> --format json -o database.json

搜索并通过管道传给 jq

notion search "project" --format json | jq '.results[] | {title: .properties.title.title[0].plain_text, url: .url}'

列出所有数据库及其 ID

notion search --type database --all --format json | jq '.results[] | {id: .id, title: .title[0].plain_text}'

递归导出页面内容

notion block list <page-id> --depth 10 --format md

凭据存储

存储位置	路径	用途
Doppler	private-config/prd:NOTION_API_TOKEN	令牌的 SSoT
CLI	~/.config/notion/credentials.json	本地身份验证缓存

令牌格式：ntn_*（Notion 内部集成令牌）。

故障排除

问题	解决方法
unauthorized	令牌已过期或被撤销——请在 notion.so/profile/integrations 重新生成
object not found	页面未连接到集成——通过页面菜单 > Connections 添加
rate_limited	CLI 会自动重试；批量操作时使用 --limit 减小批次大小
validation_error	检查属性名称是否与架构匹配：notion db view <id>

执行后反思

此技能执行完毕后，请在结束前检查：

1. 命令是否成功？ 如果没有，请修复导致失败的说明或错误表格。
2. 参数或输出是否有变化？ 如果 CLI 接口发生变化，请更新用法示例和命令表。
3. 是否需要变通方案？ 如果你不得不临时调整（使用不同标志、增加额外步骤），请更新此 SKILL.md，避免下次调用时再次遇到同样的问题。

只有在问题确实存在且可复现时才进行更新——不要臆测。