What makes Vibe Notion notable?

2K downloads. Trust evidence available

How should Vibe Notion be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

Vibe Notion

Interact with Notion using the unofficial private API - pages, databases, blocks, search, users, comments

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

2.0k

Updated

Oct 9, 2026

Version

1.5.0

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 2K downloads reported by the source. Last updated 10/9/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 9, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 9, 2026
Adoption signal: 2K downloadsadoption · observed Oct 9, 2026
Latest release: 1.5.0release · observed Apr 2, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s17e3f0kc1zca3444vg39rdjx183pefz:vibe-notion

Install using `clawhub skill install s17e3f0kc1zca3444vg39rdjx183pefz:vibe-notion` in an isolated environment before connecting it to live workloads.
No published capability contract is available yet, so validate auth and request/response behavior manually.
Review the upstream CLAWHUB listing at https://clawhub.ai/devxoul/vibe-notion before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-devxoul-vibe-notion/snapshot"

Documentation

CLAWHUB

148,198 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: vibe-notion
description: Interact with Notion using the unofficial private API - pages, databases, blocks, search, users, comments
version: 1.5.0
allowed-tools: Bash(vibe-notion:*)
metadata:
  openclaw:
    requires:
      bins:
        - vibe-notion
    install:
      - kind: node
        package: vibe-notion
        bins: [vibe-notion]
---

# Vibe Notion

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, use `vibe-notionbot`.


## Which CLI to Use

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:**

1. If the Notion desktop app is installed → use `vibe-notion` (this CLI)
2. If `NOTION_TOKEN` is set but no desktop app → use `vibe-notionbot`
3. If both are available → prefer `vibe-notion` (broader capabilities, zero setup)
4. If neither → ask the user to set up one of the two

## Important: CLI Only

**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](https://github.com/devxoul/vibe-notion/issues) 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.

## Important: Never Write Scripts

**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:
- You need to create

_meta.json

{
  "ownerId": "kn78a154cchgy7xts6ngbcyzc181mpxm",
  "slug": "vibe-notion",
  "version": "1.5.0",
  "publishedAt": 1775112626092
}

references/batch-operations.md

# 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
# 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 '[]'
```

**Supported actions** (14 total):

| Action | Description |
|--------|-------------|
| `page.create` | Create a page |
| `page.update` | Update page title, icon, or content |
| `page.archive` | Archive a page |
| `block.append` | Append blocks to a parent |
| `block.update` | Update a block |
| `block.delete` | Delete a block |
| `block.move` | Move a block to a new position |
| `comment.create` | Create a comment |
| `database.create` | Create a database |
| `database.update` | Update database title or schema |
| `database.delete-property` | Delete a database property |
| `database.add-row` | Add a row to a database |
| `database.update-row` | Update properties on a database row |
| `block.upload` | Upload a file as an image or file block |

**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": "database.add-row", "database_id": "<db_id>", "title": "Task A", "properties": {"Status": "To Do"}},
  {"action": "database.add-row", "database_id": "<db_id>", "title": "Task B", "properties": {"Status": "In Progress"}},
  {"action": "page.update", "page_id": "<page_id>", "title": "Updated Summary"}
]
```

**Output format**:

```json
{
  "results": [
    {"index": 0, "action": "database.add-row", "success": true, "data": {"id": "row-uuid-1", "...": "..."}},
    {"index": 1, "action": "database.add-row", "success": true, "data": {"id": "row-uuid-2", "...": "..."}},
    {"index": 2, "action": "page.update", "success": true, "data": {"id": "page-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": "database.add-row", "success": true, "data": {"...": "..."}},
    {"index": 1, "action": "page.update", "success": false, "error": "Page not found"}
  ],
  "total": 3,
  "succeeded": 1,
  "failed": 1
}
```

## Bulk Operations Strategy

For large operations (tens or hundreds of items), use `--file` to avoid shell argument limits and keep things manageable.

**Step 1**: Write the operations JSON to a file, then run batch with `--file`:

```bash
# Write operations to a file (using your Write tool), then:
vibe-notion batch --workspace-id <workspace_id> --file ./operations.json '[]'
```

**Multi-pass

references/block-types.md

# Block Types Reference

The internal API uses a specific block format. Here are all supported types:

## Headings

```json
{"type": "header", "properties": {"title": [["Heading 1"]]}}
{"type": "sub_header", "properties": {"title": [["Heading 2"]]}}
{"type": "sub_sub_header", "properties": {"title": [["Heading 3"]]}}
```

## Text

```json
{"type": "text", "properties": {"title": [["Plain text paragraph"]]}}
```

## Lists

```json
{"type": "bulleted_list", "properties": {"title": [["Bullet item"]]}}
{"type": "numbered_list", "properties": {"title": [["Numbered item"]]}}
```

## Nested Children

List blocks support nested children via the `children` property:

```json
{"type": "bulleted_list", "properties": {"title": [["Parent"]]}, "children": [{"type": "bulleted_list", "properties": {"title": [["Child"]]}}]}
```

## To-Do / Checkbox

```json
{"type": "to_do", "properties": {"title": [["Task item"]], "checked": [["Yes"]]}}
{"type": "to_do", "properties": {"title": [["Unchecked task"]], "checked": [["No"]]}}
```

## Code Block

```json
{"type": "code", "properties": {"title": [["console.log('hello')"]], "language": [["javascript"]]}}
```

## Quote

```json
{"type": "quote", "properties": {"title": [["Quoted text"]]}}
```

## Divider

```json
{"type": "divider"}
```

## Rich Text Formatting

Rich text uses nested arrays with formatting codes:

| Format | Syntax | Example |
|--------|--------|---------|
| Plain | `[["text"]]` | `[["Hello"]]` |
| Bold | `["text", [["b"]]]` | `["Hello", [["b"]]]` |
| Italic | `["text", [["i"]]]` | `["Hello", [["i"]]]` |
| Strikethrough | `["text", [["s"]]]` | `["Hello", [["s"]]]` |
| Inline code | `["text", [["c"]]]` | `["Hello", [["c"]]]` |
| Link | `["text", [["a", "url"]]]` | `["Click", [["a", "https://example.com"]]]` |
| Bold + Italic | `["text", [["b"], ["i"]]]` | `["Hello", [["b"], ["i"]]]` |

Multiple segments: `[["plain "], ["bold", [["b"]]], [" more plain"]]`

references/common-patterns.md

# Common Patterns for Vibe Notion

This document outlines common workflows and patterns for interacting with Notion via the CLI.

## 1. Reading Page Content Recursively

To get the full content of a page, you need to retrieve the page object and then its child blocks. If those blocks have children (e.g., nested lists, columns), you may need to fetch those recursively.

```bash
# 1. Get page metadata
vibe-notion page get <page_id> --workspace-id <workspace_id>

# 2. List direct children
vibe-notion block children <page_id> --workspace-id <workspace_id>

# 3. For any block that has "has_children: true", fetch its children
vibe-notion block children <block_id> --workspace-id <workspace_id>
```

## 2. Querying a Database and Processing Results

Querying a database returns a list of page objects. You can filter, sort, and search results.

```bash
# Query a database with a search keyword
vibe-notion database query <database_id> --workspace-id <workspace_id> --search-query "keyword" --pretty

# Query with a limit
vibe-notion database query <database_id> --workspace-id <workspace_id> --limit 10 --pretty

# Query a specific view
vibe-notion database query <database_id> --workspace-id <workspace_id> --view-id <view_id> --pretty

# Query with timezone
vibe-notion database query <database_id> --workspace-id <workspace_id> --timezone "America/New_York" --pretty
```

> **Note**: The `--filter` and `--sort` options use property IDs from the database schema (retrieved via `database get`), not property names.

## 3. Creating a Page with Initial Content

Creating a page only sets the properties (like Title). To add content, you must append blocks to the newly created page.

```bash
# 1. Create the page and capture the ID
PAGE_ID=$(vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "New Document" | jq -r '.id')

# 2. Append content blocks
vibe-notion block append $PAGE_ID --workspace-id <workspace_id> --content '[
  {"type": "header", "properties": {"title": [["Introduction"]]}},
  {"type": "text", "properties": {"title": [["This is a new page created via CLI."]]}}
]'
```

## 4. Adding Content with Markdown

Use the `--markdown` flag to append or create pages with markdown content.

```bash
# Append markdown content to an existing page
vibe-notion block append <page_id> --workspace-id <workspace_id> --markdown '# Introduction

This is a new page created via CLI.'

# Create a page with markdown content from a file
vibe-notion page create --workspace-id <workspace_id> --parent <parent_id> --title "New Document" --markdown-file ./content.md

# Replace all content on a page with new markdown
vibe-notion page update <page_id> --workspace-id <workspace_id> --replace-content --markdown-file ./updated.md
```

## 5. Updating a Page

You can update a page's title, icon, or replace its entire content.

```bash
# Update title
vibe-notion page update <page_id> --workspace-id <workspace_id> --title "New Title" --pretty

# Update icon
vibe-notion p

Github ReposUpdated 10h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.