Vibe Notionbot

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.

Which CLI to Use

This package ships two CLIs. Pick the right one based on your situation:

| | vibe-notion | vibe-notionbot (this CLI) | |---|---|---| | 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 2. If NOTION_TOKEN is set but no desktop app → use vibe-notionbot (this CLI) 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 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.

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:

If you catch yourself thinking "I should write a script for this," stop and use batch.

Quick Start

# 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  --title "My New Page"

Authentication

Integration Token (Official API)

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

export NOTION_TOKEN=secret_xxx
vibe-notionbot auth status

The integration token provides access to the official Notion API (@notionhq/client).

Commands

Page Commands

# Retrieve a page
vibe-notionbot page get 
Create a new page under a parent page or database
vibe-notionbot page create --parent  --title "New Page Title"
vibe-notionbot page create --parent  --title "New Database Item" --database
Create a page with markdown content
vibe-notionbot page create --parent  --title "My Doc" --markdown '# Hello\n\nThis is bold text.'
Create a page with markdown from a file
vibe-notionbot page create --parent  --title "My Doc" --markdown-file ./content.md
Create a page with markdown containing local images (auto-uploaded to Notion)
vibe-notionbot page create --parent  --title "My Doc" --markdown-file ./doc-with-images.md
Update page properties
vibe-notionbot page update  --set "Status=In Progress" --set "Priority=High"
Replace all content on a page with new markdown
vibe-notionbot page update  --replace-content --markdown '# New Content'
vibe-notionbot page update  --replace-content --markdown-file ./updated.md
Archive (delete) a page
vibe-notionbot page archive 
Retrieve a specific page property
vibe-notionbot page property  

Database Commands

# Retrieve a database schema
vibe-notionbot database get 
Query a database with optional filters and sorts
vibe-notionbot database query  --filter '{"property": "Status", "select": {"equals": "In Progress"}}'
vibe-notionbot database query  --sort '[{"property": "Created time", "direction": "descending"}]'
vibe-notionbot database query  --page-size 10 --start-cursor 
Create a database under a parent page
vibe-notionbot database create --parent  --title "My Database" --properties '{"Name": {"title": {}}}'
Update a database schema or title
vibe-notionbot database update  --title "Updated Title"
vibe-notionbot database update  --properties '{"Status": {"select": {"options": [{"name": "Active"}, {"name": "Archived"}]}}}'
vibe-notionbot database update  --title "Updated Title" --properties '{"Status": {"select": {}}}'
Delete a property from a database
vibe-notionbot database delete-property  --property "Status"
List all databases accessible by the integration
vibe-notionbot database list
vibe-notionbot database list --page-size 10 --start-cursor 

Block Commands

# Retrieve a block
vibe-notionbot block get 
List direct children of a block (paginated)
vibe-notionbot block children 
vibe-notionbot block children  --page-size 50 --start-cursor 
Append child blocks to a parent
vibe-notionbot block append  --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Hello World"}}]}}]'
Append markdown content as blocks
vibe-notionbot block append  --markdown '# Hello\n\nThis is bold text.'
Append markdown from a file
vibe-notionbot block append  --markdown-file ./content.md
Append markdown with local images (auto-uploaded to Notion)
vibe-notionbot block append  --markdown-file ./doc-with-images.md
Append nested markdown (indented lists become nested children blocks)
vibe-notionbot block append  --markdown '- Parent item\n  - Child item\n    - Grandchild item'
Append blocks after a specific block (positional insertion)
vibe-notionbot block append  --after  --markdown '# Inserted after specific block'
vibe-notionbot block append  --after  --content '[{"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Inserted after"}}]}}]'
Append blocks before a specific block
vibe-notionbot block append  --before  --markdown '# Inserted before specific block'
Update a block's content
vibe-notionbot block update  --content '{"paragraph": {"rich_text": [{"type": "text", "text": {"content": "Updated content"}}]}}'
Delete (archive) a block
vibe-notionbot block delete 
Upload a file as a block (image or file block)
vibe-notionbot block upload  --file ./image.png --pretty
vibe-notionbot block upload  --file ./document.pdf --pretty
vibe-notionbot block upload  --file ./image.png --after  --pretty
vibe-notionbot block upload  --file ./image.png --before  --pretty

User Commands

# List all users in the workspace
vibe-notionbot user list
vibe-notionbot user list --page-size 10 --start-cursor 
Get info for a specific user
vibe-notionbot user get 
Get info for the current bot/integration
vibe-notionbot user me

Search Commands

# 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 

Comment Commands

# List comments on a page
vibe-notionbot comment list --page 
vibe-notionbot comment list --page  --page-size 10 --start-cursor 
List inline comments on a specific block
vibe-notionbot comment list --block 
Create a comment on a page
vibe-notionbot comment create "This is a comment" --page 
Reply to a comment thread (discussion)
vibe-notionbot comment create "Replying to thread" --discussion 
Retrieve a specific comment
vibe-notionbot comment get 

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.

# Inline JSON (no --workspace-id needed, uses NOTION_TOKEN)
vibe-notionbot batch ''
From file (for large payloads)
vibe-notionbot batch --file ./operations.json '[]'

Supported actions (11 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 | | 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:

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

Output format:

{
  "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.

{
  "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
}

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:

# Write operations to a file (using your Write tool), then:
vibe-notionbot batch --file ./operations.json '[]'

Multi-pass pattern — when new items need to reference each other (e.g., a page property linking to another newly created page):

1. Pass 1 — Create all items (without cross-references): Write a batch JSON file with all create operations, omitting properties that point to other new items. Run it. Collect the returned IDs from the output. 2. Pass 2 — Set cross-references: Write a second batch JSON file with update operations that set the referencing properties using the IDs from Pass 1. Run it.

Pass 1: Create items A, B, C (no cross-refs) → get IDs for A, B, C
Pass 2: Update A.related=B, C.parent_ref=A (using real IDs from Pass 1)

This is the same result as a script, but without writing any code. Just two batch calls.

Rate Limits

Notion enforces rate limits on its API. Batch operations run sequentially, so a large batch (30+ operations) can trigger 429 Too Many Requests errors. To avoid this:

Split large batches into chunks of ~25-30 operations per batch call If a batch fails mid-way with a 429, re-run with only the remaining (unprocessed) operations The batch output shows which operations succeeded before the failure — use the index field to determine where to resume

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

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

Pretty (Human-Readable)

Use --pretty flag for formatted output:

vibe-notionbot search "Project" --pretty

Error Handling

Common errors from the Notion API:

Troubleshooting

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:

npx -y -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.

Limitations

# 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  --title "My New Page"

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:

npx -y -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.