Vibe Notionbot

A TypeScript CLI tool that enables AI agents and humans to interact with Notion workspaces through the official Notion API. Supports pages, databases, blocks, users, comments, and search.

一款TypeScript CLI工具，支持AI Agent和人类通过官方Notion API与Notion工作区进行交互。支持页面、数据库、块、用户、评论和搜索功能。

Important: CLI Only

重要提示：仅支持CLI

Never call the Notion API directly. Always use the

vibe-notionbot

CLI commands described in this skill. Do not make raw HTTP requests to the Notion API or use

@notionhq/client

directly. 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-notionbot

, 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.

切勿直接调用Notion API。 请始终使用本技能中描述的

vibe-notionbot

CLI命令。不要向Notion API发送原始HTTP请求，也不要直接使用

@notionhq/client

。直接调用API可能会泄露凭证，还可能触发Notion的滥用检测机制，导致用户账号被封禁。

如果

vibe-notionbot

不支持你需要的功能，请告知用户，并代表他们在devxoul/vibe-notion提交功能请求。提交前，请去除所有真实用户数据——ID、姓名、邮箱、令牌、页面内容或任何可识别用户或其工作区的信息。改用通用占位符，且仅聚焦于描述缺失的功能。

Quick Start

快速开始

bash

undefined

bash

undefined

Check authentication status

vibe-notionbot auth status

Search for a page or database

vibe-notionbot search "Project Roadmap"

List all databases

vibe-notionbot database list

Create a new page

vibe-notionbot page create --parent <parent_id> --title "My New Page"

undefined

vibe-notionbot page create --parent <parent_id> --title "My New Page"

undefined

Authentication

身份验证

Integration Token (Official API)

集成令牌（官方API）

Set the

NOTION_TOKEN

environment variable with your integration token from the Notion Developer Portal.

bash

export NOTION_TOKEN=secret_xxx
vibe-notionbot auth status

The integration token provides access to the official Notion API (

@notionhq/client

).

在环境变量中设置

NOTION_TOKEN

，值为你从Notion开发者门户获取的集成令牌。

bash

export NOTION_TOKEN=secret_xxx
vibe-notionbot auth status

该集成令牌可用于访问官方Notion API（

@notionhq/client

）。

Commands

命令

Page Commands

页面命令

bash

undefined

bash

undefined

Retrieve a page

vibe-notionbot page get <page_id>

Create a new page under a parent page or database

vibe-notionbot page create --parent <parent_id> --title "New Page Title" vibe-notionbot page create --parent <database_id> --title "New Database Item" --database

Create a page with markdown content

vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown '# Hello\n\nThis is bold text.'

Create a page with markdown from a file

vibe-notionbot page create --parent <parent_id> --title "My Doc" --markdown-file ./content.md

Update page properties

vibe-notionbot page update <page_id> --set "Status=In Progress" --set "Priority=High"

Replace all content on a page with new markdown

vibe-notionbot page update <page_id> --replace-content --markdown '# New Content' vibe-notionbot page update <page_id> --replace-content --markdown-file ./updated.md

Archive (delete) a page

vibe-notionbot page archive <page_id>

Retrieve a specific page property

vibe-notionbot page property <page_id> <property_id>

undefined

vibe-notionbot page property <page_id> <property_id>

undefined

Database Commands

数据库命令

bash

undefined

bash

undefined

Retrieve a database schema

vibe-notionbot database get <database_id>

Query a database with optional filters and sorts

vibe-notionbot database query <database_id> --filter '{"property": "Status", "select": {"equals": "In Progress"}}' vibe-notionbot database query <database_id> --sort '[{"property": "Created time", "direction": "descending"}]' vibe-notionbot database query <database_id> --page-size 10 --start-cursor <cursor>

Create a database under a parent page

vibe-notionbot database create --parent <page_id> --title "My Database" --properties '{"Name": {"title": {}}}'

Update a database schema or title

vibe-notionbot database update <database_id> --title "Updated Title"

Delete a property from a database

vibe-notionbot database delete-property <database_id> --property "Status"

List all databases accessible by the integration

vibe-notionbot database list vibe-notionbot database list --page-size 10 --start-cursor <cursor>

undefined

vibe-notionbot database list vibe-notionbot database list --page-size 10 --start-cursor <cursor>

undefined

Block Commands

块命令

bash

undefined

bash

undefined

Retrieve a block

vibe-notionbot block get <block_id>

List direct children of a block (paginated)

vibe-notionbot block children <block_id> vibe-notionbot block children <block_id> --page-size 50 --start-cursor <cursor>

Append child blocks to a parent

vibe-notionbot block append <parent_id> --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Hello World"}}]}}]'

Append markdown content as blocks

vibe-notionbot block append <parent_id> --markdown '# Hello\n\nThis is bold text.'

Append markdown from a file

vibe-notionbot block append <parent_id> --markdown-file ./content.md

Update a block's content

vibe-notionbot block update <block_id> --content '{"paragraph": {"rich_text": [{"type": "text", "text": {"content": "Updated content"}}]}}'

Delete (archive) a block

vibe-notionbot block delete <block_id>

undefined

vibe-notionbot block delete <block_id>

undefined

User Commands

用户命令

bash

undefined

bash

undefined

List all users in the workspace

vibe-notionbot user list vibe-notionbot user list --page-size 10 --start-cursor <cursor>

Get info for a specific user

vibe-notionbot user get <user_id>

Get info for the current bot/integration

vibe-notionbot user me

undefined

vibe-notionbot user me

undefined

Search Commands

搜索命令

bash

undefined

bash

undefined

Search across the entire workspace

vibe-notionbot search "query text"

Filter search by object type

vibe-notionbot search "Project" --filter page vibe-notionbot search "Tasks" --filter database

Sort search results

vibe-notionbot search "Meeting" --sort desc

Paginate search results

vibe-notionbot search "Notes" --page-size 10 --start-cursor <cursor>

undefined

vibe-notionbot search "Notes" --page-size 10 --start-cursor <cursor>

undefined

Comment Commands

评论命令

bash

undefined

bash

undefined

List comments on a page

vibe-notionbot comment list --page <page_id> vibe-notionbot comment list --page <page_id> --page-size 10 --start-cursor <cursor>

Create a comment on a page

vibe-notionbot comment create "This is a comment" --page <page_id>

Reply to a comment thread (discussion)

vibe-notionbot comment create "Replying to thread" --discussion <discussion_id>

Retrieve a specific comment

vibe-notionbot comment get <comment_id>

undefined

vibe-notionbot comment get <comment_id>

undefined

Batch Operations

批量操作

Run multiple write operations in a single CLI call. Use this instead of calling the CLI repeatedly when you need to create, update, or delete multiple things at once. Saves tokens and reduces round-trips.

bash

undefined

在单个CLI调用中运行多个写入操作。当你需要一次性创建、更新或删除多个内容时，请使用此功能，而非重复调用CLI。这样可以节省令牌并减少往返请求次数。

bash

undefined

Inline JSON (no --workspace-id needed, uses NOTION_TOKEN)

vibe-notionbot batch '<operations_json>'

From file (for large payloads)

vibe-notionbot batch --file ./operations.json '[]'


**Supported actions** (10 total):

| Action | Description |
|--------|-------------|
| `page.create` | Create a page |
| `page.update` | Update page properties |
| `page.archive` | Archive a page |
| `block.append` | Append blocks to a parent |
| `block.update` | Update a block |
| `block.delete` | Delete a block |
| `comment.create` | Create a comment |
| `database.create` | Create a database |
| `database.update` | Update database title or schema |
| `database.delete-property` | Delete a database property |

**Operation format**: Each operation is an object with `action` plus the same fields you'd pass to the individual command handler. Example with mixed actions:

```json
[
  {"action": "page.create", "parent": "<parent_id>", "title": "Meeting Notes"},
  {"action": "block.append", "parent_id": "<page_id>", "markdown": "# Agenda\n\n- Item 1\n- Item 2"},
  {"action": "comment.create", "content": "Page created via batch", "page": "<page_id>"}
]

Output format:

json

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"id": "page-uuid", "...": "..."}},
    {"index": 1, "action": "block.append", "success": true, "data": {"...": "..."}},
    {"index": 2, "action": "comment.create", "success": true, "data": {"id": "comment-uuid", "...": "..."}}
  ],
  "total": 3,
  "succeeded": 3,
  "failed": 0
}

Fail-fast behavior: Operations run sequentially. If any operation fails, execution stops immediately. The output will contain results for all completed operations plus the failed one. The process exits with code 1 on failure, 0 on success.

json

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"...": "..."}},
    {"index": 1, "action": "block.append", "success": false, "error": "Block not found"}
  ],
  "total": 3,
  "succeeded": 1,
  "failed": 1
}

vibe-notionbot batch --file ./operations.json '[]'


**支持的操作**（共10种）：

| 操作 | 描述 |
|--------|-------------|
| `page.create` | 创建页面 |
| `page.update` | 更新页面属性 |
| `page.archive` | 归档页面 |
| `block.append` | 向父块添加子块 |
| `block.update` | 更新块内容 |
| `block.delete` | 删除块 |
| `comment.create` | 创建评论 |
| `database.create` | 创建数据库 |
| `database.update` | 更新数据库标题或架构 |
| `database.delete-property` | 删除数据库属性 |

**操作格式**：每个操作是一个包含`action`的对象，加上你传递给单个命令处理程序的相同字段。以下是混合操作的示例：

```json
[
  {"action": "page.create", "parent": "<parent_id>", "title": "Meeting Notes"},
  {"action": "block.append", "parent_id": "<page_id>", "markdown": "# Agenda\n\n- Item 1\n- Item 2"},
  {"action": "comment.create", "content": "Page created via batch", "page": "<page_id>"}
]

输出格式：

json

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"id": "page-uuid", "...": "..."}},
    {"index": 1, "action": "block.append", "success": true, "data": {"...": "..."}},
    {"index": 2, "action": "comment.create", "success": true, "data": {"id": "comment-uuid", "...": "..."}}
  ],
  "total": 3,
  "succeeded": 3,
  "failed": 0
}

快速失败行为：操作按顺序运行。如果任何操作失败，执行将立即停止。输出将包含所有已完成操作的结果以及失败的操作。失败时进程以代码1退出，成功时以代码0退出。

json

{
  "results": [
    {"index": 0, "action": "page.create", "success": true, "data": {"...": "..."}},
    {"index": 1, "action": "block.append", "success": false, "error": "Block not found"}
  ],
  "total": 3,
  "succeeded": 1,
  "failed": 1
}

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:

json

{
  "id": "...",
  "object": "page",
  "properties": { ... }
}

所有命令默认输出JSON格式，供AI处理：

json

{
  "id": "...",
  "object": "page",
  "properties": { ... }
}

Pretty (Human-Readable)

美化格式（人类可读）

Use

--pretty

flag for formatted output:

bash

vibe-notionbot search "Project" --pretty

使用

--pretty

标志获取格式化输出：

bash

vibe-notionbot search "Project" --pretty

Error Handling

错误处理

Common errors from the Notion API:

```
object_not_found
```
: The ID is incorrect or the integration doesn't have access.
```
unauthorized
```
: The
```
NOTION_TOKEN
```
is invalid.
```
rate_limited
```
: Too many requests.

Notion API常见错误：

```
object_not_found
```
：ID不正确，或集成无访问权限。
```
unauthorized
```
：
```
NOTION_TOKEN
```
无效。
```
rate_limited
```
：请求过于频繁。

Troubleshooting

故障排除

vibe-notionbot: command not found

vibe-notionbot: command not found

The

vibe-notion

package is not installed. Run it directly using a package runner. Ask the user which one to use:

bash

npx -p vibe-notion vibe-notionbot ...
bunx -p vibe-notion vibe-notionbot ...
pnpm dlx --package vibe-notion vibe-notionbot ...

If you already know the user's preferred package runner, use it directly instead of asking.

未安装

vibe-notion

包。使用包运行器直接执行。询问用户使用哪一个：

bash

npx -p vibe-notion vibe-notionbot ...
bunx -p vibe-notion vibe-notionbot ...
pnpm dlx --package vibe-notion vibe-notionbot ...

如果你已了解用户偏好的包运行器，请直接使用，无需询问。

Limitations

限制

Supports Notion API version 2022-06-28.
Does not support OAuth (token only).
Does not support file uploads in v1.
Page property updates are limited to simple key=value pairs unless using raw JSON.

支持Notion API版本2022-06-28。
不支持OAuth（仅支持令牌）。
v1版本不支持文件上传。
页面属性更新仅限于简单的键值对，除非使用原始JSON。

vibe-notionbot

Original

Translation

Vibe Notionbot

Vibe Notionbot

Important: CLI Only

重要提示：仅支持CLI

Quick Start

快速开始

Check authentication status

Check authentication status

Search for a page or database

Search for a page or database

List all databases

List all databases

Create a new page

Create a new page

Authentication

身份验证

Integration Token (Official API)

集成令牌（官方API）

Commands

命令

Page Commands

页面命令

Retrieve a page

Retrieve a page

Create a new page under a parent page or database

Create a new page under a parent page or database

Create a page with markdown content

Create a page with markdown content

Create a page with markdown from a file

Create a page with markdown from a file

Update page properties

Update page properties

Replace all content on a page with new markdown

Replace all content on a page with new markdown

Archive (delete) a page

Archive (delete) a page

Retrieve a specific page property

Retrieve a specific page property

Database Commands

数据库命令

Retrieve a database schema

Retrieve a database schema

Query a database with optional filters and sorts

Query a database with optional filters and sorts

Create a database under a parent page

Create a database under a parent page

Update a database schema or title

Update a database schema or title

Delete a property from a database

Delete a property from a database

List all databases accessible by the integration

List all databases accessible by the integration

Block Commands

块命令

Retrieve a block

Retrieve a block

List direct children of a block (paginated)

List direct children of a block (paginated)

Append child blocks to a parent

Append child blocks to a parent

Append markdown content as blocks

Append markdown content as blocks

Append markdown from a file

Append markdown from a file

Update a block's content

Update a block's content

Delete (archive) a block

Delete (archive) a block

User Commands

用户命令

List all users in the workspace

List all users in the workspace

Get info for a specific user

Get info for a specific user

Get info for the current bot/integration

Get info for the current bot/integration

Search Commands

`vibe-notionbot: command not found`

`vibe-notionbot: command not found`