vibe-notion

Vibe Notion

Give your AI agent the power to read and write Notion pages, databases, and more.

A full-coverage, agent-friendly CLI for the Notion API. Ships two CLIs — vibe-notion for the unofficial private API (act as yourself) and vibe-notionbot for the official Integration API (act as a bot).

Table of Contents

• Why Vibe Notion?
• Installation
• Agent Skills
  • SkillPad
  • Skills CLI
  • Claude Code Plugin
  • OpenCode Plugin
• Quick Start
• Command Overview
• Use Cases
  • Research & Discovery
  • Project Tracking
  • Creating & Writing
  • Automation & Pipelines
  • ...and More
• Philosophy
• Contributing
• License

Why Vibe Notion?

Notion's official API only supports Integration (bot) tokens — your agent can't do things on behalf of you. Vibe Notion solves this by extracting your token_v2 from the Notion desktop app, so your agent operates as you, with your full permissions.

Need official API access instead? vibe-notionbot is included and fully supports Integration tokens via NOTION_TOKEN.

• Act as you — vibe-notion extracts token_v2 from the Notion desktop app to operate with your own permissions
• Bot support too — vibe-notionbot supports official Integration tokens via NOTION_TOKEN
• Full API coverage — Pages, databases, blocks, users, search, comments, and workspaces
• Agent friendly — JSON output by default, perfect for LLM tool use
• Agent memory — Remembers workspace IDs, page names, and preferences across sessions
• Token efficient — CLI, not MCP. Load only what you need. (Why not MCP?)

Installation

npm install -g vibe-notion

Or use your favorite package manager.

This installs both the vibe-notion and vibe-notionbot CLI tools.

Agent Skills

Vibe Notion includes Agent Skills that teach your AI agent how to use the CLI effectively. Two skills are available:

• vibe-notion — For the unofficial private API (token_v2)
• vibe-notionbot — For the official Integration API (NOTION_TOKEN)

SkillPad

SkillPad is a GUI app for Agent Skills. See skillpad.dev for more details.

Skills CLI

Skills CLI is a CLI tool for Agent Skills. See skills.sh for more details.

npx skills add devxoul/vibe-notion

Claude Code Plugin

/plugin marketplace add devxoul/vibe-notion
/plugin install vibe-notion

OpenCode Plugin

Add to your opencode.jsonc:

{
  "plugins": [
    "vibe-notion"
  ]
}

Quick Start

vibe-notion (Private API — act as yourself)

# 1. List your workspaces
vibe-notion workspace list --pretty

# 2. Search for something
vibe-notion search "Roadmap" --workspace-id <workspace-id> --pretty

# 3. Get page details
vibe-notion page get <page-id> --workspace-id <workspace-id> --pretty

vibe-notionbot (Official API — act as a bot)

# 1. Set your Notion Integration Token
export NOTION_TOKEN=secret_xxx

# 2. Check auth status
vibe-notionbot auth status --pretty

# 3. Search for something
vibe-notionbot search "Roadmap" --filter page --pretty

# 4. Get page details
vibe-notionbot page get <page-id> --pretty

Command Overview

vibe-notion (Private API)

Command	Description
auth	Extract token, check status, logout
workspace	List accessible workspaces
page	Get, list, create, update, archive pages
database	Get schema, query, create, update, delete properties, add/update rows, list, manage views
block	Get, list children, append (with nested markdown support), update, delete blocks
user	Get current user, get user by ID
search	Workspace search
comment	List, create, and get comments (including inline block-level comments)