重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
vibe-notion by devxoul/vibe-notion
npx skills add https://github.com/devxoul/vibe-notion --skill vibe-notion一个 TypeScript CLI 工具,使 AI 代理和人类能够通过非官方的私有 API 与 Notion 工作区进行交互。支持对页面、数据库、块、搜索和用户管理的完整 CRUD 操作。
注意:此技能使用 Notion 的内部/私有 API (
/api/v3/),与官方的公共 API 是分开的。如需访问官方 API,请使用vibe-notionbot。
此包提供了两个 CLI。根据您的情况选择正确的 CLI:
| vibe-notion (此 CLI) | vibe-notionbot
---|---|---
API | 非官方的私有 API | 官方的 Notion API
认证 | 从 Notion 桌面应用自动提取的 token_v2 | NOTION_TOKEN 环境变量(集成令牌)
身份 | 作为用户操作 | 作为机器人操作
设置 | 零配置 — 凭证自动提取 | 手动 — 在 notion.so/my-integrations 创建集成
数据库行 | add-row, update-row | 通过 创建
视图管理 | , , , , | 不支持
工作区列表 | 支持 | 不支持
稳定性 | 私有 API — 可能在 Notion 变更时失效 | 官方版本化 API — 稳定
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
page create --databaseview-getview-updateview-listview-addview-delete决策流程:
vibe-notion (此 CLI)NOTION_TOKEN 但没有桌面应用 → 使用 vibe-notionbotvibe-notion(功能更广,零设置)切勿直接调用 Notion 的内部 API。 请始终使用本技能中描述的 vibe-notion CLI 命令。不要向 notion.so/api/v3/ 发送原始 HTTP 请求或使用任何 Notion 客户端库。直接调用 API 有暴露凭证的风险,并可能触发 Notion 的滥用检测,导致用户账户被封锁。
如果您需要的功能 vibe-notion 不支持,请告知用户并主动提出代表他们在 devxoul/vibe-notion 提交功能请求。提交前,请删除任何真实的用户数据 — ID、姓名、电子邮件、令牌、页面内容或任何可能识别用户或其工作区的信息。使用通用占位符代替,并确保问题专注于描述缺失的功能。
切勿编写脚本(Python、TypeScript、Bash 等)来自动化 Notion 操作。 batch 命令已经可以处理任何规模的批量操作。编写脚本来循环调用 API 总是错误的 — 请改用带 --file 的 batch 命令。
即使以下情况也适用:
如果您发现自己想“我应该为此写个脚本”,请停下来并使用 batch。
# 1. 查找您的工作区 ID
vibe-notion workspace list --pretty
# 2. 搜索页面
vibe-notion search "Roadmap" --workspace-id <workspace-id> --pretty
# 3. 获取页面内容
vibe-notion page get <page-id> --workspace-id <workspace-id> --pretty
# 4. 查询数据库
vibe-notion database query <collection-id> --workspace-id <workspace-id> --pretty
凭证在首次使用时从 Notion 桌面应用自动提取。无需手动设置。
重要:
--workspace-id是所有在特定工作区内操作的命令所必需的。使用vibe-notion workspace list来查找您的工作区 ID。
凭证 (token_v2) 在您运行任何命令时从 Notion 桌面应用自动提取。无需 API 密钥、OAuth 或手动提取。
在 macOS 上,您的系统可能会在首次使用时提示访问钥匙串 — 这是正常的,也是解密 cookie 所必需的。
提取的 token_v2 存储在 ~/.config/vibe-notion/credentials.json,权限为 0600。
代理维护一个 ~/.config/vibe-notion/MEMORY.md 文件作为跨会话的持久记忆。这是由代理管理的 — CLI 不读取或写入此文件。使用 Read 和 Write 工具来管理您的记忆文件。
在每个任务开始时,使用 Read 工具读取 ~/.config/vibe-notion/MEMORY.md,以加载之前发现的任何工作区 ID、页面 ID、数据库 ID 和用户偏好。
发现有用信息后,使用 Write 工具更新 ~/.config/vibe-notion/MEMORY.md。写入触发条件包括:
workspace list)search、page list、page get、database list 等)写入时,包含完整的文件内容 — Write 工具会覆盖整个文件。
切勿存储 token_v2、凭证、API 密钥或任何敏感数据。切勿存储完整的页面内容(仅存储 ID 和标题)。除非是持久性引用(如数据库块),否则切勿存储块级 ID。
如果记忆的 ID 返回错误(页面未找到、访问被拒绝),请将其从 MEMORY.md 中移除。不要盲目信任记忆的数据 — 当某些地方看起来不对劲时进行验证。相比于使用可能已过时的记忆 ID,更倾向于重新搜索。
以下是构建 MEMORY.md 的具体示例:
# Vibe Notion 记忆
## 工作区
- `abc123-...` — Acme Corp (默认)
## 页面 (Acme Corp)
- `page-id-1` — 产品路线图 (顶层)
- `page-id-2` — Q1 规划 (在产品路线图下)
## 数据库 (Acme Corp)
- `coll-id-1` — 任务 (在产品路线图下,视图: `view-1`)
- `coll-id-2` — 联系人 (顶层)
## 别名
- "roadmap" → `page-id-1` (产品路线图)
- "tasks" → `coll-id-1` (任务数据库)
## 备注
- 用户偏好搜索结果使用 --pretty 输出
- 主工作区是 "Acme Corp"
记忆让您可以跳过重复的
search和workspace list调用。当您从之前的会话中已经知道一个 ID 时,直接使用它。
vibe-notion auth status # 检查认证状态
vibe-notion auth logout # 移除存储的 token_v2
vibe-notion auth extract # 手动重新提取 token_v2 (用于故障排除)
# 列出空间中的页面 (仅顶层)
vibe-notion page list --workspace-id <workspace_id> --pretty
vibe-notion page list --workspace-id <workspace_id> --depth 2 --pretty
# 获取页面及其所有内容块
vibe-notion page get <page_id> --workspace-id <workspace_id> --pretty
vibe-notion page get <page_id> --workspace-id <workspace_id> --limit 50
vibe-notion page get <page_id> --workspace-id <workspace_id> --backlinks --pretty
# 创建新页面 (--parent 是可选的;省略则在工作区根目录创建)
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Page" --pretty
vibe-notion page create --workspace-id <workspace_id> --title "New Root Page" --pretty
# 使用 markdown 内容创建页面
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Doc" --markdown '# Hello\n\nThis is **bold** text.'
# 使用文件中的 markdown 创建页面
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Doc" --markdown-file ./content.md
# 使用包含本地图片的 markdown 创建页面 (自动上传到 Notion)
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Doc" --markdown-file ./doc-with-images.md
# 用新的 markdown 替换页面上的所有内容
vibe-notion page update <page_id> --workspace-id <workspace_id> --replace-content --markdown '# New Content'
vibe-notion page update <page_id> --workspace-id <workspace_id> --replace-content --markdown-file ./updated.md
# 更新页面标题或图标
vibe-notion page update <page_id> --workspace-id <workspace_id> --title "New Title" --pretty
vibe-notion page update <page_id> --workspace-id <workspace_id> --icon "🚀" --pretty
# 归档页面
vibe-notion page archive <page_id> --workspace-id <workspace_id> --pretty
# 获取页面或数据库行属性 (不含内容块 — 是 page get 的轻量级替代方案)
vibe-notion page properties <page_id> --workspace-id <workspace_id> --pretty
# 获取数据库架构
vibe-notion database get <database_id> --workspace-id <workspace_id> --pretty
# 查询数据库 (自动解析默认视图)
vibe-notion database query <database_id> --workspace-id <workspace_id> --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --limit 10 --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --view-id <view_id> --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --search-query "keyword" --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --timezone "America/New_York" --pretty
# 使用过滤器和排序进行查询 (使用来自 database get 架构的属性 ID)
vibe-notion database query <database_id> --workspace-id <workspace_id> --filter '<filter_json>' --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --sort '<sort_json>' --pretty
# 列出工作区中的所有数据库
vibe-notion database list --workspace-id <workspace_id> --pretty
# 创建数据库
vibe-notion database create --workspace-id <workspace_id> --parent <page_id> --title "Tasks" --pretty
vibe-notion database create --workspace-id <workspace_id> --parent <page_id> --title "Tasks" --properties '{"status":{"name":"Status","type":"select"}}' --pretty
# 更新数据库标题或架构
vibe-notion database update <database_id> --workspace-id <workspace_id> --title "New Name" --pretty
vibe-notion database update <database_id> --workspace-id <workspace_id> --properties '{"status":{"name":"Status","type":"select"}}' --pretty
vibe-notion database update <database_id> --workspace-id <workspace_id> --title "New Name" --properties '{"status":{"name":"Status","type":"select"}}' --pretty
# 向数据库添加一行
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Row title" --pretty
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Row title" --properties '{"Status":"In Progress","Due":{"start":"2025-03-01"}}' --pretty
# 添加带日期范围的行
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Event" --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty
# 更新现有数据库行的属性 (row_id 来自 database query)
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Status":"Done"}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Priority":"High","Tags":["backend","infra"]}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Due":{"start":"2026-06-01"},"Status":"In Progress"}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Related":["<target_row_id>"]}' --pretty
# 从数据库中删除属性 (不能删除标题属性)
vibe-notion database delete-property <database_id> --workspace-id <workspace_id> --property "Status" --pretty
# 获取视图配置和属性可见性
vibe-notion database view-get <view_id> --workspace-id <workspace_id> --pretty
# 在视图上显示或隐藏属性 (逗号分隔的名称)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --show "ID,Due" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --hide "Assignee" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --show "Status" --hide "Due" --pretty
# 重新排序列 (逗号分隔的名称,按所需顺序;未提及的列将追加)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --reorder "Name,Status,Priority,Date" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --reorder "Name,Status" --show "Status" --pretty
# 调整列宽 (JSON 映射属性名到像素宽度)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --resize '{"Name":200,"Status":150}' --pretty
# 列出数据库的所有视图
vibe-notion database view-list <database_id> --workspace-id <workspace_id> --pretty
# 向数据库添加新视图 (默认类型: table)
vibe-notion database view-add <database_id> --workspace-id <workspace_id> --pretty
vibe-notion database view-add <database_id> --workspace-id <workspace_id> --type board --name "Board View" --pretty
# 从数据库中删除视图 (不能删除最后一个视图)
vibe-notion database view-delete <view_id> --workspace-id <workspace_id> --pretty
简单表格(非数据库) — 嵌入在页面中的轻量级表格。
# 创建带表头和可选行的简单表格
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "Name,Role,Score" --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "Name,Role,Score" --rows '[["Alice","Dev","95"],["Bob","PM","88"]]' --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "A,B" --after <block_id> --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "A,B" --before <block_id> --pretty
# 向简单表格添加一行
vibe-notion table add-row <table_id> --workspace-id <workspace_id> --cells "Charlie,QA,92" --pretty
# 更新单个单元格 (行和列是 0 索引,不包括表头行)
vibe-notion table update-cell <table_id> --workspace-id <workspace_id> --row 0 --col 1 --value "Lead" --pretty
# 删除一行 (0 索引,不包括表头行)
vibe-notion table delete-row <table_id> --workspace-id <workspace_id> --row 0 --pretty
简单表格 vs 数据库:简单表格是内联的、轻量级的网格,没有架构、过滤器或视图。对于具有类型化属性、过滤和排序的结构化数据,请使用
database命令。
# 获取特定块
vibe-notion block get <block_id> --workspace-id <workspace_id> --pretty
vibe-notion block get <block_id> --workspace-id <workspace_id> --backlinks --pretty
# 列出子块
vibe-notion block children <block_id> --workspace-id <workspace_id> --pretty
vibe-notion block children <block_id> --workspace-id <workspace_id> --limit 50 --pretty
vibe-notion block children <block_id> --workspace-id <workspace_id> --start-cursor '<next_cursor_json>' --pretty
# 追加子块
vibe-notion block append <parent_id> --workspace-id <workspace_id> --content '[{"type":"text","properties":{"title":[["Hello world"]]}}]' --pretty
# 将 markdown 内容作为块追加
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown '# Hello\n\nThis is **bold** text.'
# 从文件追加 markdown
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown-file ./content.md
# 追加包含本地图片的 markdown (自动上传到 Notion)
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown-file ./doc-with-images.md
# 追加嵌套的 markdown (缩进列表变为嵌套子块)
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown '- Parent item\n - Child item\n - Grandchild item'
# 在特定块后追加块 (位置插入)
vibe-notion block append <parent_id> --workspace-id <workspace_id> --after <block_id> --markdown '# Inserted after specific block'
vibe-notion block append <parent_id> --workspace-id <workspace_id> --after <block_id> --content '[{"type":"text","properties":{"title":[["Inserted after"]]}}]'
# 在特定块前追加块
vibe-notion block append <parent_id> --workspace-id <workspace_id> --before <block_id> --markdown '# Inserted before specific block'
# 更新块
vibe-notion block update <block_id> --workspace-id <workspace_id> --content '{"properties":{"title":[["Updated text"]]}}' --pretty
# 删除块
vibe-notion block delete <block_id> --workspace-id <workspace_id> --pretty
# 将文件作为块上传 (图片或文件块)
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./image.png --pretty
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./document.pdf --pretty
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./image.png --after <block_id> --pretty
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./image.png --before <block_id> --pretty
# 将块移动到新位置
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --pretty
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --after <sibling_id> --pretty
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --before <sibling_id> --pretty
关于块类型 JSON 格式(标题、文本、列表、待办事项、代码、引用、分隔符)和富文本格式化代码,请参阅 references/block-types.md。
# 列出页面上的评论
vibe-notion comment list --page <page_id> --workspace-id <workspace_id> --pretty
# 列出特定块上的内联评论
vibe-notion comment list --page <page_id> --block <block_id> --workspace-id <workspace_id> --pretty
# 在页面上创建评论 (开始新的讨论)
vibe-notion comment create "This is a comment" --page <page_id> --workspace-id <workspace_id> --pretty
# 回复现有的讨论线程
vibe-notion comment create "Replying to thread" --discussion <discussion_id> --workspace-id <workspace_id> --pretty
# 通过 ID 获取特定评论
vibe-notion comment get <comment_id> --workspace-id <workspace_id> --pretty
关于批量命令格式、支持的操作(共 14 种)、操作 JSON 结构、输出格式、快速失败行为、批量操作策略(多轮模式)和速率限制处理,请参阅 references/batch-operations.md。
快速用法:
# 内联 JSON
vibe-notion batch --workspace-id <workspace_id> '<operations_json>'
# 从文件 (用于大型负载)
vibe-notion batch --workspace-id <workspace_id> --file ./operations.json '[]'
# 跨工作区搜索 (--workspace-id 是必需的)
vibe-notion search "query" --workspace-id <workspace_id> --pretty
vibe-notion search "query" --workspace-id <workspace_id> --limit 10 --pretty
vibe-notion search "query" --workspace-id <workspace_id> --start-cursor <offset> --pretty
vibe-notion search "query" --workspace-id <workspace_id> --sort lastEdited --pretty
# 获取当前用户信息
vibe-notion user me --pretty
# 获取特定用户
vibe-notion user get <user_id> --workspace-id <workspace_id> --pretty
# 列出工作区中的用户
vibe-notion user list --workspace-id <workspace_id> --pretty
所有命令默认输出 JSON。使用 --pretty 获取人类可读的输出。
关于 JSON 响应结构(搜索、数据库查询、页面获取、块获取、反向链接)、$hints 架构警告和详细示例,请参阅 references/output-format.md。
--backlinks反向链接揭示哪些页面/数据库链接到给定页面。这对于高效导航至关重要。
在以下情况下使用 --backlinks:
示例 — 查找谁使用了特定计划:
# 糟糕:15 个 API 调用 — 搜索、打开空页面、追踪父级、查找数据库、查询
vibe-notion search "Enterprise Plan" ...
vibe-notion page get <plan-page-id> ... # 空的
vibe-notion block get <plan-page-id> ... # 查找父级
# ... 更多调用来发现数据库
# 良好:2-3 个 API 调用 — 搜索,然后在目标上使用反向链接
vibe-notion search "Enterprise Plan" ...
vibe-notion page get <plan-page-id> --backlinks --pretty
# → 反向链接立即显示所有链接到此计划的人员/行
返回列表的命令通过 has_more、next_cursor 字段支持分页:
block children:基于游标。将先前响应中的 next_cursor 值作为 --start-cursor 传递。search:基于偏移量。将 next_cursor 值(一个数字)作为 --start-cursor 传递。database query:使用 --limit 控制页面大小。has_more 表示存在更多结果,但私有 API 不支持基于游标的分页 — 增加 --limit 以获取更多行。如果自动提取失败(例如,未安装 Notion 桌面应用或未登录),请手动运行提取命令以获取调试输出:
vibe-notion auth extract --debug
这将显示 Notion 目录路径和提取步骤,以帮助诊断问题。
如果 auth extract 失败并显示:
{"error":"No token_v2 found. Make sure Notion desktop app is installed and logged in."}
并且 Notion 桌面应用已安装并登录,则 cookie 数据库可能被正在运行的 Notion 应用锁定。告诉用户完全退出 Notion 桌面应用,然后重试命令。一旦凭证被提取,用户可以重新打开 Notion。
vibe-notion: command not foundvibe-notion 包未安装。使用包运行器直接运行它。询问用户使用哪个:
npx -y vibe-notion ...
bunx vibe-notion ...
pnpm dlx vibe-notion ...
如果您已经知道用户偏好的包运行器,请直接使用它而不是询问。
token_v2 使用非官方的内部 API,如果 Notion 更改它,可能会失效。每周安装数
84
仓库
GitHub 星标数
16
首次出现
2026 年 2 月 17 日
安全审计
安装于
opencode76
gemini-cli68
kimi-cli64
amp64
github-copilot64
codex64
A TypeScript CLI tool that enables AI agents and humans to interact with Notion workspaces through the unofficial private API. Supports full CRUD operations on pages, databases, blocks, search, and user management.
Note : This skill uses Notion's internal/private API (
/api/v3/), which is separate from the official public API. For official API access, usevibe-notionbot.
This package ships two CLIs. Pick the right one based on your situation:
| vibe-notion (this CLI) | vibe-notionbot
---|---|---
API | Unofficial private API | Official Notion API
Auth | token_v2 auto-extracted from Notion desktop app | NOTION_TOKEN env var (Integration token)
Identity | Acts as the user | Acts as a bot
Setup | Zero — credentials extracted automatically | Manual — create Integration at notion.so/my-integrations
Database rows | add-row, update-row | Create via page create --database
View management | view-get, view-update, view-list, view-add, view-delete | Not supported
Workspace listing | Supported | Not supported
Stability | Private API — may break on Notion changes | Official versioned API — stable
Decision flow:
vibe-notion (this CLI)NOTION_TOKEN is set but no desktop app → use vibe-notionbotvibe-notion (broader capabilities, zero setup)Never call Notion's internal API directly. Always use the vibe-notion CLI commands described in this skill. Do not make raw HTTP requests to notion.so/api/v3/ or use any Notion client library. Direct API calls risk exposing credentials and may trigger Notion's abuse detection, getting the user's account blocked.
If a feature you need is not supported by vibe-notion, let the user know and offer to file a feature request at devxoul/vibe-notion on their behalf. Before submitting, strip out any real user data — IDs, names, emails, tokens, page content, or anything else that could identify the user or their workspace. Use generic placeholders instead and keep the issue focused on describing the missing capability.
Never write scripts (Python, TypeScript, Bash, etc.) to automate Notion operations. The batch command already handles bulk operations of any size. Writing a script to loop through API calls is always wrong — use batch with --file instead.
This applies even when:
If you catch yourself thinking "I should write a script for this," stop and use batch.
# 1. Find your workspace ID
vibe-notion workspace list --pretty
# 2. Search for a page
vibe-notion search "Roadmap" --workspace-id <workspace-id> --pretty
# 3. Get page content
vibe-notion page get <page-id> --workspace-id <workspace-id> --pretty
# 4. Query a database
vibe-notion database query <collection-id> --workspace-id <workspace-id> --pretty
Credentials are auto-extracted from the Notion desktop app on first use. No manual setup needed.
Important :
--workspace-idis required for ALL commands that operate within a specific workspace. Usevibe-notion workspace listto find your workspace ID.
Credentials (token_v2) are auto-extracted from the Notion desktop app when you run any command. No API keys, OAuth, or manual extraction needed.
On macOS, your system may prompt for Keychain access on first use — this is normal and required to decrypt the cookie.
The extracted token_v2 is stored at ~/.config/vibe-notion/credentials.json with 0600 permissions.
The agent maintains a ~/.config/vibe-notion/MEMORY.md file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the Read and Write tools to manage your memory file.
At the start of every task , read ~/.config/vibe-notion/MEMORY.md using the Read tool to load any previously discovered workspace IDs, page IDs, database IDs, and user preferences.
After discovering useful information, update ~/.config/vibe-notion/MEMORY.md using the Write tool. Write triggers include:
workspace list)search, page list, page get, database list, etc.)When writing, include the complete file content — the Write tool overwrites the entire file.
Never store token_v2, credentials, API keys, or any sensitive data. Never store full page content (just IDs and titles). Never store block-level IDs unless they're persistent references (like database blocks).
If a memorized ID returns an error (page not found, access denied), remove it from MEMORY.md. Don't blindly trust memorized data — verify when something seems off. Prefer re-searching over using a memorized ID that might be stale.
Here's a concrete example of how to structure your MEMORY.md:
# Vibe Notion Memory
## Workspaces
- `abc123-...` — Acme Corp (default)
## Pages (Acme Corp)
- `page-id-1` — Product Roadmap (top-level)
- `page-id-2` — Q1 Planning (under Product Roadmap)
## Databases (Acme Corp)
- `coll-id-1` — Tasks (under Product Roadmap, views: `view-1`)
- `coll-id-2` — Contacts (top-level)
## Aliases
- "roadmap" → `page-id-1` (Product Roadmap)
- "tasks" → `coll-id-1` (Tasks database)
## Notes
- User prefers --pretty output for search results
- Main workspace is "Acme Corp"
Memory lets you skip repeated
searchandworkspace listcalls. When you already know an ID from a previous session, use it directly.
vibe-notion auth status # Check authentication status
vibe-notion auth logout # Remove stored token_v2
vibe-notion auth extract # Manually re-extract token_v2 (for troubleshooting)
# List pages in a space (top-level only)
vibe-notion page list --workspace-id <workspace_id> --pretty
vibe-notion page list --workspace-id <workspace_id> --depth 2 --pretty
# Get a page and all its content blocks
vibe-notion page get <page_id> --workspace-id <workspace_id> --pretty
vibe-notion page get <page_id> --workspace-id <workspace_id> --limit 50
vibe-notion page get <page_id> --workspace-id <workspace_id> --backlinks --pretty
# Create a new page (--parent is optional; omit to create at workspace root)
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Page" --pretty
vibe-notion page create --workspace-id <workspace_id> --title "New Root Page" --pretty
# Create a page with markdown content
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Doc" --markdown '# Hello\n\nThis is **bold** text.'
# Create a page with markdown from a file
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Doc" --markdown-file ./content.md
# Create a page with markdown containing local images (auto-uploaded to Notion)
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "My Doc" --markdown-file ./doc-with-images.md
# Replace all content on a page with new markdown
vibe-notion page update <page_id> --workspace-id <workspace_id> --replace-content --markdown '# New Content'
vibe-notion page update <page_id> --workspace-id <workspace_id> --replace-content --markdown-file ./updated.md
# Update page title or icon
vibe-notion page update <page_id> --workspace-id <workspace_id> --title "New Title" --pretty
vibe-notion page update <page_id> --workspace-id <workspace_id> --icon "🚀" --pretty
# Archive a page
vibe-notion page archive <page_id> --workspace-id <workspace_id> --pretty
# Get page or database row properties (without content blocks — lightweight alternative to page get)
vibe-notion page properties <page_id> --workspace-id <workspace_id> --pretty
# Get database schema
vibe-notion database get <database_id> --workspace-id <workspace_id> --pretty
# Query a database (auto-resolves default view)
vibe-notion database query <database_id> --workspace-id <workspace_id> --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --limit 10 --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --view-id <view_id> --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --search-query "keyword" --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --timezone "America/New_York" --pretty
# Query with filter and sort (uses property IDs from database get schema)
vibe-notion database query <database_id> --workspace-id <workspace_id> --filter '<filter_json>' --pretty
vibe-notion database query <database_id> --workspace-id <workspace_id> --sort '<sort_json>' --pretty
# List all databases in workspace
vibe-notion database list --workspace-id <workspace_id> --pretty
# Create a database
vibe-notion database create --workspace-id <workspace_id> --parent <page_id> --title "Tasks" --pretty
vibe-notion database create --workspace-id <workspace_id> --parent <page_id> --title "Tasks" --properties '{"status":{"name":"Status","type":"select"}}' --pretty
# Update database title or schema
vibe-notion database update <database_id> --workspace-id <workspace_id> --title "New Name" --pretty
vibe-notion database update <database_id> --workspace-id <workspace_id> --properties '{"status":{"name":"Status","type":"select"}}' --pretty
vibe-notion database update <database_id> --workspace-id <workspace_id> --title "New Name" --properties '{"status":{"name":"Status","type":"select"}}' --pretty
# Add a row to a database
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Row title" --pretty
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Row title" --properties '{"Status":"In Progress","Due":{"start":"2025-03-01"}}' --pretty
# Add row with date range
vibe-notion database add-row <database_id> --workspace-id <workspace_id> --title "Event" --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty
# Update properties on an existing database row (row_id from database query)
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Status":"Done"}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Priority":"High","Tags":["backend","infra"]}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Due":{"start":"2026-06-01"},"Status":"In Progress"}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Due":{"start":"2026-01-01","end":"2026-01-15"}}' --pretty
vibe-notion database update-row <row_id> --workspace-id <workspace_id> --properties '{"Related":["<target_row_id>"]}' --pretty
# Delete a property from a database (cannot delete the title property)
vibe-notion database delete-property <database_id> --workspace-id <workspace_id> --property "Status" --pretty
# Get view configuration and property visibility
vibe-notion database view-get <view_id> --workspace-id <workspace_id> --pretty
# Show or hide properties on a view (comma-separated names)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --show "ID,Due" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --hide "Assignee" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --show "Status" --hide "Due" --pretty
# Reorder columns (comma-separated names in desired order; unmentioned columns appended)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --reorder "Name,Status,Priority,Date" --pretty
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --reorder "Name,Status" --show "Status" --pretty
# Resize columns (JSON mapping property names to pixel widths)
vibe-notion database view-update <view_id> --workspace-id <workspace_id> --resize '{"Name":200,"Status":150}' --pretty
# List all views for a database
vibe-notion database view-list <database_id> --workspace-id <workspace_id> --pretty
# Add a new view to a database (default type: table)
vibe-notion database view-add <database_id> --workspace-id <workspace_id> --pretty
vibe-notion database view-add <database_id> --workspace-id <workspace_id> --type board --name "Board View" --pretty
# Delete a view from a database (cannot delete the last view)
vibe-notion database view-delete <view_id> --workspace-id <workspace_id> --pretty
Simple tables (non-database) — lightweight tables embedded in pages.
# Create a simple table with headers and optional rows
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "Name,Role,Score" --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "Name,Role,Score" --rows '[["Alice","Dev","95"],["Bob","PM","88"]]' --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "A,B" --after <block_id> --pretty
vibe-notion table create <parent_id> --workspace-id <workspace_id> --headers "A,B" --before <block_id> --pretty
# Add a row to a simple table
vibe-notion table add-row <table_id> --workspace-id <workspace_id> --cells "Charlie,QA,92" --pretty
# Update a single cell (row and col are 0-indexed, excluding header row)
vibe-notion table update-cell <table_id> --workspace-id <workspace_id> --row 0 --col 1 --value "Lead" --pretty
# Delete a row (0-indexed, excluding header row)
vibe-notion table delete-row <table_id> --workspace-id <workspace_id> --row 0 --pretty
Simple tables vs databases : Simple tables are inline, lightweight grids with no schema, filters, or views. Use
databasecommands for structured data with typed properties, filtering, and sorting.
# Get a specific block
vibe-notion block get <block_id> --workspace-id <workspace_id> --pretty
vibe-notion block get <block_id> --workspace-id <workspace_id> --backlinks --pretty
# List child blocks
vibe-notion block children <block_id> --workspace-id <workspace_id> --pretty
vibe-notion block children <block_id> --workspace-id <workspace_id> --limit 50 --pretty
vibe-notion block children <block_id> --workspace-id <workspace_id> --start-cursor '<next_cursor_json>' --pretty
# Append child blocks
vibe-notion block append <parent_id> --workspace-id <workspace_id> --content '[{"type":"text","properties":{"title":[["Hello world"]]}}]' --pretty
# Append markdown content as blocks
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown '# Hello\n\nThis is **bold** text.'
# Append markdown from a file
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown-file ./content.md
# Append markdown with local images (auto-uploaded to Notion)
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown-file ./doc-with-images.md
# Append nested markdown (indented lists become nested children blocks)
vibe-notion block append <parent_id> --workspace-id <workspace_id> --markdown '- Parent item\n - Child item\n - Grandchild item'
# Append blocks after a specific block (positional insertion)
vibe-notion block append <parent_id> --workspace-id <workspace_id> --after <block_id> --markdown '# Inserted after specific block'
vibe-notion block append <parent_id> --workspace-id <workspace_id> --after <block_id> --content '[{"type":"text","properties":{"title":[["Inserted after"]]}}]'
# Append blocks before a specific block
vibe-notion block append <parent_id> --workspace-id <workspace_id> --before <block_id> --markdown '# Inserted before specific block'
# Update a block
vibe-notion block update <block_id> --workspace-id <workspace_id> --content '{"properties":{"title":[["Updated text"]]}}' --pretty
# Delete a block
vibe-notion block delete <block_id> --workspace-id <workspace_id> --pretty
# Upload a file as a block (image or file block)
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./image.png --pretty
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./document.pdf --pretty
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./image.png --after <block_id> --pretty
vibe-notion block upload <parent_id> --workspace-id <workspace_id> --file ./image.png --before <block_id> --pretty
# Move a block to a new position
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --pretty
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --after <sibling_id> --pretty
vibe-notion block move <block_id> --workspace-id <workspace_id> --parent <parent_id> --before <sibling_id> --pretty
For block type JSON format (headings, text, lists, to-do, code, quote, divider) and rich text formatting codes, see references/block-types.md.
# List comments on a page
vibe-notion comment list --page <page_id> --workspace-id <workspace_id> --pretty
# List inline comments on a specific block
vibe-notion comment list --page <page_id> --block <block_id> --workspace-id <workspace_id> --pretty
# Create a comment on a page (starts a new discussion)
vibe-notion comment create "This is a comment" --page <page_id> --workspace-id <workspace_id> --pretty
# Reply to an existing discussion thread
vibe-notion comment create "Replying to thread" --discussion <discussion_id> --workspace-id <workspace_id> --pretty
# Get a specific comment by ID
vibe-notion comment get <comment_id> --workspace-id <workspace_id> --pretty
For batch command format, supported actions (14 total), operation JSON structure, output format, fail-fast behavior, bulk operations strategy (multi-pass pattern), and rate limit handling, see references/batch-operations.md.
Quick usage:
# Inline JSON
vibe-notion batch --workspace-id <workspace_id> '<operations_json>'
# From file (for large payloads)
vibe-notion batch --workspace-id <workspace_id> --file ./operations.json '[]'
# Search across workspace (--workspace-id is required)
vibe-notion search "query" --workspace-id <workspace_id> --pretty
vibe-notion search "query" --workspace-id <workspace_id> --limit 10 --pretty
vibe-notion search "query" --workspace-id <workspace_id> --start-cursor <offset> --pretty
vibe-notion search "query" --workspace-id <workspace_id> --sort lastEdited --pretty
# Get current user info
vibe-notion user me --pretty
# Get a specific user
vibe-notion user get <user_id> --workspace-id <workspace_id> --pretty
# List users in a workspace
vibe-notion user list --workspace-id <workspace_id> --pretty
All commands output JSON by default. Use --pretty for human-readable output.
For JSON response shapes (search, database query, page get, block get, backlinks), $hints schema warnings, and detailed examples, see references/output-format.md.
--backlinksBacklinks reveal which pages/databases link to a given page. This is critical for efficient navigation.
Use--backlinks when:
Example — finding who uses a specific plan:
# BAD: 15 API calls — search, open empty pages, trace parents, find database, query
vibe-notion search "Enterprise Plan" ...
vibe-notion page get <plan-page-id> ... # empty
vibe-notion block get <plan-page-id> ... # find parent
# ... many more calls to discover the database
# GOOD: 2-3 API calls — search, then backlinks on the target
vibe-notion search "Enterprise Plan" ...
vibe-notion page get <plan-page-id> --backlinks --pretty
# → backlinks immediately show all people/rows linked to this plan
Commands that return lists support pagination via has_more, next_cursor fields:
block children : Cursor-based. Pass next_cursor value from previous response as --start-cursor.search : Offset-based. Pass next_cursor value (a number) as --start-cursor.database query : Use --limit to control page size. has_more indicates more results exist, but the private API does not support cursor-based pagination — increase --limit to fetch more rows.If auto-extraction fails (e.g., Notion desktop app is not installed or not logged in), run the extract command manually for debug output:
vibe-notion auth extract --debug
This shows the Notion directory path and extraction steps to help diagnose the issue.
If auth extract fails with:
{"error":"No token_v2 found. Make sure Notion desktop app is installed and logged in."}
And the Notion desktop app is installed and logged in, the cookie database may be locked by the running Notion app. Tell the user to quit the Notion desktop app completely, then retry the command. Once credentials are extracted, the user can reopen Notion.
vibe-notion: command not foundThe vibe-notion package is not installed. Run it directly using a package runner. Ask the user which one to use:
npx -y vibe-notion ...
bunx vibe-notion ...
pnpm dlx vibe-notion ...
If you already know the user's preferred package runner, use it directly instead of asking.
token_v2 uses the unofficial internal API and may break if Notion changes it.Weekly Installs
84
Repository
GitHub Stars
16
First Seen
Feb 17, 2026
Security Audits
Gen Agent Trust HubPassSocketWarnSnykPass
Installed on
opencode76
gemini-cli68
kimi-cli64
amp64
github-copilot64
codex64
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
48,700 周安装
ArXiv论文对话AI:智能搜索、问答与文献综述助手,提升科研效率
110 周安装
AI Agent Skills 最佳实践指南:46条规则优化Claude技能与MCP工具开发
110 周安装
Remotion 视频脚本生成器 | AI 自动生成产品演示、编码教程、数据可视化视频脚本
110 周安装
JavaScript/TypeScript 包体积优化工具 - 自动化减小 Bundle 大小
111 周安装
Markdown转HTML转换器 - 微信公众号优化,支持多主题样式
112 周安装
Remotion 最佳实践指南:动画、3D、音频、图表等完整开发教程
111 周安装