用途
notion-cli 用于在命令行中与 Notion 交互，适合 CLI 优先、便于管道处理的操作。典型用途包括搜索 Notion、查询数据库、读取页面、导出数据、管理区块以及添加评论。它封装了通过 brew install 4ier/tap/notion-cli 安装的 Go 二进制 notion。
不适用场景：基于 Notion SDK 的 Python 自动化，应改用 productivity-tools:notion-sdk。
主要能力
- 搜索：按标题搜索，可按 page 或 database 类型筛选，支持全部结果分页抓取与结果数量限制。
- 页面操作：查看页面内容（区块转为 Markdown）、查看属性、创建页面、设置属性、在 $EDITOR 中编辑、移动、归档、恢复、在浏览器中打开、列出可访问页面。
- 数据库操作：列出数据库、查看 schema、查询行、使用简单或 JSON 复杂过滤器、排序、抓取全部页面、导出为 CSV/JSON/Markdown 表格、添加单行或从 JSON 批量添加。过滤器运算符包括 = != > >= < <= ~=（包含）；多个 --filter 以 AND 组合，OR 逻辑需用 --filter-json。
- 区块操作：列出子区块（可递归指定深度）、获取指定区块、以 Markdown 追加、在指定区块后插入、删除、移动。
- 评论：列出评论、添加评论、回复评论。
- 用户与文件：查看当前 bot 用户、列出工作区用户、获取用户详情；上传文件、列出上传内容。
- 原生 API：通过 notion api 发送 GET/POST 请求，支持 --body 或从标准输入传入请求体。
使用方式
输出格式：CLI 会自动检测上下文，TTY（交互终端）输出彩色表格，被管道接收（如传给 jq、文件）时输出干净 JSON。可用 --format 强制指定：json、table、md、text。面向 agent 消费时，始终通过管道或使用 --format json 获取结构化输出。
ID 解析：Notion URL 与原始 ID 可互换使用。
认证前置检查：执行任何操作前，先用 notion auth status 验证是否已认证。若未认证，从 Doppler 获取令牌并认证：doppler secrets get NOTION_API_TOKEN --project claude-config --config prd --plain | notion auth login --with-token。回退方案：提示用户提供其集成令牌。
凭据存储：Doppler 的 claude-config/prd:NOTION_API_TOKEN 是令牌的单一事实来源；CLI 本地认证缓存位于 ~/.config/notion/credentials.json。令牌格式为 ntn_*（Notion 内部集成令牌）。
适用场景
需要从命令行或脚本中检索、查询、导出 Notion 内容，并把结构化输出交给其他工具处理的场景。
限制与故障排查
- unauthorized：令牌过期或被撤销，需在 notion.so/profile/integrations 重新生成。
- object not found：页面未连接到集成，需通过页面菜单 > Connections 添加。
- rate_limited：CLI 会自动重试；批量操作可用 --limit 减小批次大小。
- validation_error：检查属性名是否与 schema 匹配，可用 notion db view <id> 查看。
其他未在资料中提供的信息暂未提供。