notion-cli-agent

The most powerful command-line interface for Notion — built for AI agents first, humans too.

notion-cli-agent is designed to be used by AI agents that need to read and write Notion workspaces — natural language queries, batch operations, --llm output mode, workspace introspection, and more. Works great for humans too.

---

🤖 For AI Agents

Quick start

npm install -g notion-cli-agent
export NOTION_TOKEN="ntn_your_token_here"

# Full quick reference (read this first)
notion quickstart

Agent Skills (recommended)

This repo ships AgentSkills-compatible skill files in the skills/ directory. Skills use progressive disclosure: the core SKILL.md is small enough to live in your agent’s context window, and detailed reference files (filters.md, batch-patterns.md, workflows.md) are loaded on demand.

skills/
├── notion-onboarding/    ← run first: maps your workspace to a state file
└── notion-cli-agent/     ← core CLI skill + references

Recommended setup for agents:

1. Install skills in your agent framework (see skills/README.md)
2. Run the notion-onboarding skill once — it discovers your databases (tasks, projects, OKRs, home page) and saves them to ~/.config/notion/workspace.json
3. All subsequent tasks use the mapped IDs automatically — no more looking up database IDs

Why a CLI over the Notion MCP/API?

• --llm mode — compact, structured output optimized for agent consumption
• notion find — natural language → Notion filters in one command
• notion batch — multiple operations in a single shell call (minimize tool calls)
• notion ai prompt — generates a database-specific prompt for the agent
• notion inspect context — full schema + examples + command reference in one shot
• No rate-limit boilerplate, no SDK setup, shell-composable

---

✨ Features

Core Operations

• Search — Find pages and databases across your workspace
• Pages — Create, read, update, archive pages with full property support
• Databases — Query with filters, create schemas, manage entries
• Blocks — Add and manage page content (paragraphs, headings, lists, code, etc.)
• Comments — Read and create comments on pages
• Files — Upload images and attachments to pages, properties, icons/covers, and comments
• Users — List workspace users and integrations

🤖 AI Agent Features

• Smart Queries — Natural language queries translated to Notion filters
• Batch Operations — Execute multiple operations in one command
• Agent Prompts — Generate optimal prompts for AI agents to work with databases
• Summarize — Get concise page summaries
• Extract — Pull structured data from page content

🔄 Obsidian Integration

• Export to Obsidian — Pages and databases with YAML frontmatter
• Import from Obsidian — Import vault notes to Notion
• CSV & Markdown import — Bulk import from files

📊 Analytics & Validation

• Statistics — Database metrics, breakdowns by property
• Timeline — Activity visualization over time
• Health Check — Database integrity scoring
• Validation — Find missing fields, overdue items, stale entries

🔗 Advanced Features

• Workspace Sync — Cache databases locally, use names instead of UUIDs everywhere
• Templates — Save and reuse page structures
• Backup — Full database backup to JSON/Markdown
• Duplicate — Clone pages and entire databases
• Relations — Manage links, find backlinks, visualize graphs
• Bulk Operations — Update or archive hundreds of entries at once

---

📦 Installation

From npm (recommended)

npm install -g notion-cli-agent

From source

# Clone the repository
git clone https://github.com/Balneario-de-Cofrentes/notion-cli-agent.git
cd notion-cli-agent

# Install dependencies
pnpm install

# Build
pnpm build

# Link globally
pnpm link --global

Requirements

• Node.js 20+
• A Notion integration token (create one here)

---

⚙️ Configuration

1. Get your API token

1. Go to notion.so/my-integrations
2. Click “New integration”
3. Give it a name and select capabilities
4. Copy the token (starts with ntn_ or secret_)

2. Set the token

# Option 1: Environment variable (recommended)
export NOTION_TOKEN="ntn_your_token_here"

# Option 2: Pass directly
notion --token "ntn_xxx" search "query"

3. Share content with your integration

Important: Your integration can only access pages explicitly shared with it.

1. Open any page or database in Notion
2. Click “…” menu → “Connect to” → Select your integration

---

🔄 Workspace Sync

Sync your workspace to use database names instead of UUIDs:

# Cache all accessible databases locally
notion sync

# List cached databases
notion list
notion list --json         # For scripts
notion list --ids-only     # One ID per line

# Now use names anywhere you'd use a database UUID
notion db query "Tasks" --limit 5
notion find "Tasks" "overdue assigned to me"
notion validate health "Projects"
notion stats overview "OKRs"

All database commands accept both UUIDs and names. Name resolution uses case-insensitive matching with substring fallback. If a name is ambiguous, the CLI shows candidates and asks you to be more specific.

---

📖 Usage Guide

Basic Commands

# Search across workspace
notion search "project plan"
notion search "meeting" --type page
notion search "" --type database    # List all databases

# Exact lookup in a known database (deterministic)
notion db query  --title "Known Page" --json

# Filtered search (best-effort — Notion search is fuzzy)
notion search "keyword" --db  --exact --first --json
notion search "task" --db                    # Filter by parent database

# Get page info
notion page get 
notion page get  --content  # Include blocks

# Create page in database
notion page create --parent  --title "New Task"
notion page create --parent  --title "Bug Fix" \
  --prop "Status=Todo" \
  --prop "Priority=High"
notion page create --parent  --title "Meeting Notes" --icon 📝

# Update page
notion page update  --prop "Status:status=Done"
notion page update  --title "New Title"
notion page update  --icon 🚀
notion page update  --clear-prop "Assignee"  # Type-aware clear

# Archive page
notion page archive 

Output Formats

# Export database as CSV
notion db query  --csv > tasks.csv

# Tab-separated (paste into spreadsheets)
notion db query  --tsv | pbcopy

# Just IDs for piping into other commands
notion db query  --filter "Status=Done" --ids-only | \
  xargs -I {} notion page archive {}

# Count search results
notion search "bugs" --ids-only | wc -l

---

📄 Page Content (read/write/edit)

Read, write, and surgically edit page content as Markdown.

# Read page content as Markdown (uses native Notion markdown API)
notion page read 
notion page read  --blocks        # Legacy: fetch blocks and convert client-side
notion page read  --json          # Raw block JSON output
notion page read  -o page.md      # Write to file

# Write Markdown content into a page
notion page write  -f content.md
echo "# Hello" | notion page write 
notion page write  -f doc.md --replace   # Replace all content (destructive)

# Surgical block-level editing
notion page edit  --at 3 --delete 2                    # Delete 2 blocks at index 3
notion page edit  --at 5 --markdown "New paragraph"    # Insert at index 5
notion page edit  --at 0 --delete 1 --file new.md      # Replace first block
notion page edit  --dry-run --at 3 --delete 1          # Preview without changes

---

📎 Files & Attachments

Upload images and attachments to Notion. Anywhere a `` is accepted it can be a local path, a public URL (Notion imports it server-side), or an existing file_upload ID (attach the same upload again without re-uploading). Files over 20 MB are split into parts automatically.

# Upload and attach in one call (block type detected from the file)
notion file attach  shot.png
notion file attach  a.pdf b.png --caption "Q3 report"
notion file attach  clip.mp4 --as video --after 

# Upload only — prints the file_upload ID for later use
notion file upload shot.png                       # → ID: 1a2b3c4d-...
notion file upload a.pdf b.png --json
notion file import https://example.com/logo.png   # Import from a public URL

# Inspect uploads
notion file list --status uploaded
notion file get 

# Attach while adding content
notion block append  --text "See below" --image shot.png --caption "Diagram"
notion block append  --pdf report.pdf --file data.zip

# Page icon, cover, and files properties
notion page update  --icon logo.png --cover https://example.com/hero.jpg
notion page update  --attach "Attachments=spec.pdf,diagram.png"
notion page create --parent  -t "Release" --attach "Docs=notes.md"

# Comments (max 3 attachments)
notion comment create --page  -t "Screenshot attached" --attach shot.png

--icon still takes an emoji (--icon 📝); anything that looks like a path, URL, or upload ID is uploaded instead.

URL imports need a file extension. Notion requires a filename with an extension, and many CDN URLs end in a bare ID. Supply one with --content-type (or --name) and reuse the resulting ID:

notion file import https://images.unsplash.com/photo-1506744038136 --content-type image/jpeg
notion page update  --cover 

---

🤖 AI Agent Features

Smart Queries with find

Translate natural language into Notion filters:

# Find overdue tasks
notion find "overdue tasks" -d 

# Find unassigned items in progress
notion find "in progress unassigned" -d 

# Find high priority pending items
notion find "urgent pending" -d 

# See what filter was generated
notion find "tareas vencidas" -d  --explain

Supported patterns:

• Status: done, in progress, todo, pending, hecho, en marcha
• Assignment: unassigned, sin asignar
• Dates: overdue, vencidas, today, this week
• Priority: urgent, high priority, importante

Batch Operations

Execute multiple operations in one command — perfect for AI agents to minimize tool calls:

# Preview what would happen
notion batch --dry-run --data '[
  {"op": "get", "type": "page", "id": "abc123"},
  {"op": "create", "type": "page", "parent": "db_id", "data": {...}},
  {"op": "update", "type": "page", "id": "xyz789", "data": {...}}
]'

# Execute with LLM-friendly output
notion batch --llm --data '[...]'

# Read from file
notion batch -f operations.json

Supported operations:

Generate Agent Prompts

Create optimal prompts for AI agents to work with a specific database:

notion ai prompt 

Output includes:

• Database schema with all properties
• Valid values for select/status fields (exact spelling matters!)
• Example entries
• Common operations with correct syntax
• Warnings about property naming (e.g., “Title is called ‘Título’, not ‘Name’”)

Summarize Pages

Get concise summaries for quick understanding:

notion ai summarize 

# Output:
# Project Plan Q1
# Last edited: 2 days ago
# Blocks: 45
# Properties:
#   - Status: In Progress
#   - Owner: Juan
# Sections:
#   - Overview
#   - Timeline
#   - Resources
# Todos: 8/12 completed

Extract Structured Data

Pull specific data points from page content:

notion ai extract  --schema "email,phone,company,date"

# Output:
{
  "email": "[email protected]",
  "phone": "+34 612 345 678",
  "company": "Acme Corp",
  "date": "2024-03-15"
}

Command Suggestions

Get command suggestions based on natural language:

notion ai suggest  "quiero ver las tareas completadas esta semana"

# Outputs:
# notion find "hecho" -d 
# notion db query  --filter-prop "Status" --filter-value "Hecho" --filter-prop-type status

---

🔄 Obsidian Integration

Export to Obsidian

Export a single page:

notion export page  --obsidian -o my-note.md

Export entire database to vault:

notion export db  --vault ~/obsidian-vault --folder notion-tasks

With full page content:

notion export db  --vault ~/vault --content

Exported files include:

---
notion_id: "abc123..."
notion_url: "https://notion.so/..."
created: 2024-01-15
updated: 2024-02-01
status: "In Progress"
priority: "High"
tags:
  - "project"
  - "q1"
---
# Page Title

Content here...

Import from Obsidian

Import vault to database:

notion import obsidian ~/my-vault --to 
notion import obsidian ~/my-vault --to  --folder specific-folder
notion import obsidian ~/my-vault --to  --content  # Include page content

Import CSV:

notion import csv data.csv --to 
notion import csv tasks.csv --to  --title-column "Task Name"

Import Markdown file:

notion import markdown document.md --to 
notion import markdown doc.md --to  --replace  # Replace existing content

---

📊 Database Analytics

Statistics Overview

notion stats overview 

# Output:
# 📊 Database: Tasks
#    Total entries: 342
#
# Status:
#   Done                 124 (36%)  ████████
#   In Progress           89 (26%)  ██████
#   Todo                  78 (23%)  █████
#   Blocked               51 (15%)  ███
#
# Priority:
#   High                  45 (13%)  ███
#   Medium               187 (55%)  ███████████
#   Low                  110 (32%)  ███████

Activity Timeline

notion stats timeline  --days 14

# 2024-02-01 (Thu)  12 ████████████
# 2024-01-31 (Wed)   8 ████████
# 2024-01-30 (Tue)  15 ███████████████
# ...

---

✅ Validation & Health

Full Validation

notion validate check  \
  --required "Assignee,Deadline" \
  --check-dates \
  --check-stale 30 \
  --fix

# Output:
# ⚠️ MISSING REQUIRED (23)
#    - Task ABC: Missing required property: Assignee
#    - Task XYZ: Missing required property: Deadline
#    Fix: notion page update  --prop "Assignee=..."
#
# ⚠️ OVERDUE (8)
#    - Old task: Overdue: deadline was 2024-01-15
#
# ℹ️ STALE (5)
#    - Stuck item: Not updated in 45 days (status: In Progress)
#
# 📊 Health Score: 72/100

Quick Lint

notion validate lint 

# ✅ Empty titles: OK
# ⚠️ "In Progress" for >30 days: 5 found
# Total issues: 5

Health Report

notion validate health 

# 📊 Health Report: Tasks
# ════════════════════════════════════════
# Health Score: 78/100 🟡
# ════════════════════════════════════════
#
# 📈 Activity (last 7 days): 34/100 entries (34%)
# ✅ Completion rate: 65%
# 📝 Average fill rate: 82%
#
# Property fill rates:
#   ✅ Title         ██████████ 100%
#   ✅ Status        ██████████ 100%
#   ⚠️ Assignee      ████████░░ 77%
#   ❌ Tags          ██░░░░░░░░ 15%

---

💾 Backup & Restore

Full Database Backup

# Backup to JSON
notion backup  -o ./backups/tasks

# Backup to Markdown
notion backup  -o ./backups --format markdown

# Include page content
notion backup  -o ./backups --content

# Incremental backup (only changed entries)
notion backup  -o ./backups --incremental

Output structure:

backups/
├── schema.json           # Database schema
├── index.json            # Entry index
├── .backup-meta.json     # Backup metadata
└── pages/
    ├── Task_One_abc123.json
    ├── Task_Two_def456.json
    └── ...

---

🧹 Dedup — Find & Clean Duplicates

# Find duplicate pages by title
notion dedup 

# Include near-duplicates (strips copy/draft suffixes)
notion dedup  --fuzzy

# Archive duplicates, keep the page with most content
notion dedup  --fix --strategy keep-largest --yes

# Keep newest or oldest
notion dedup  --fix --strategy keep-newest --yes
notion dedup  --fix --strategy keep-oldest --yes

# Preview first (default when --fix without --yes)
notion dedup  --fix --strategy keep-largest

---

🔗 Relations & Backlinks

Find Backlinks

Discover what pages link to a specific page:

notion relations backlinks 

# 📎 Direct Relations:
#    Project Alpha
#    └─ via property: Related Tasks
#
#    Sprint 23
#    └─ via property: Tasks
#
# 📝 Potential Mentions:
#    Meeting Notes Jan 15
#    Weekly Report

Link/Unlink Pages

# Create relation
notion relations link   --property "Related"

# Bidirectional linking
notion relations link   --property "Related" --bidirectional

# Remove relation
notion relations unlink   --property "Related"

Visualize Relationship Graph

# Text format
notion relations graph  --depth 2

# DOT format (for Graphviz)
notion relations graph  --format dot > graph.dot
dot -Tpng graph.dot -o graph.png

# JSON format
notion relations graph  --format json

---

📋 Templates

Save a Page as Template

notion template save  --name "weekly-report" --description "Weekly team report"

List Templates

notion template list

# 📄 weekly-report
#    Blocks: 15
#    Description: Weekly team report
#
# 📄 meeting-notes
#    Blocks: 8

Use Template

notion template use "weekly-report" --parent  --title "Report Week 5"

Manage Templates

notion template show "weekly-report"  # View details
notion template delete "weekly-report"  # Remove

---

🔄 Bulk Operations

Bulk Update

Update multiple entries at once:

# Preview first
notion bulk update  --where "Status=Todo" --set "Status=In Progress" --dry-run

# Execute
notion bulk update  --where "Status=Todo" --set "Status=In Progress" --yes

Bulk Archive

Archive entries matching a condition:

# Archive completed items older than 2024
notion bulk archive  --where "Status=Done" --dry-run
notion bulk archive  --where "Status=Done" --yes

Where clause syntax:

• Equals: Property=Value
• Multiple conditions: Status=Done,Priority=Low

---

🔍 Workspace Introspection

List Accessible Databases

notion inspect workspace
notion inspect ws --compact  # Just names and IDs

Get Database Schema

notion inspect schema 
notion inspect schema  --llm  # Optimized for AI consumption

Generate Context for AI

notion inspect context 

# Outputs comprehensive context including:
# - Schema with all properties and valid values
# - Example entries
# - Quick command reference

---

🔌 Raw API Access

For operations not covered by other commands:

# GET request
notion api GET "pages/"

# POST with body
notion api POST "search" --data '{"query": "test"}'

# With query parameters
notion api GET "users" --query "page_size=5"

---

📝 Property Formats

When setting properties with --prop, the CLI auto-detects types:

Type hints — Force a specific property type with Key:type=Value:

# Status properties (vs auto-detected select)
notion page update  --prop "Status:status=Done"

# Rich text instead of select
notion page update  --prop "Notes:rich_text=Some notes"

# People by user ID, email, or name
notion page update  --prop "Assignee:people=user-id-here"
notion page update  --prop "Assignee:[email protected]"   # resolved to id
notion page update  --prop "Assignee:people=Ana Pérez"          # case-insensitive name

Assigning guests. Notion’s GET /v1/users (and notion user list) only returns members and bots — guest users are invisible and you can’t list their id. Run notion user resolve-guests once: it discovers guests from page authorship (created_by/last_edited_by) via GET /v1/users/{id} and caches them in ~/.config/notion/guests.json. After that, notion user list shows them flagged [guest], and --prop "Field:people=" resolves members (live list) and guests (cache) — exact email first, then case-insensitive name. notion sync fishes guests too. Non-UUID values that match nothing pass through unchanged.

For database queries with non-select properties:

notion db query  \
  --filter-prop "Status" \
  --filter-type equals \
  --filter-value "Done" \
  --filter-prop-type status  # Required for status type

---

🔌 MCP Server Mode

Run as an MCP tool server for agent frameworks (Claude Code, Cursor, VS Code):

notion --mcp

Configure in Claude Code (settings.json):

{
  "mcpServers": {
    "notion": {
      "command": "notion",
      "args": ["--mcp"],
      "env": { "NOTION_TOKEN": "ntn_your_token" }
    }
  }
}

Exposes 14 tools: search, page_get, page_create, page_update, db_query, db_schema, block_children, block_append, find, batch, inspect_workspace, comment_create, validate_health, dedup.

---

🎯 Command Reference

---

📦 Agent Skills

The skills/ directory contains AgentSkills-compatible packages for use with OpenClaw, Claude Code, Cursor, and other agent frameworks.

Structure

skills/
├── README.md                               # Installation & overview
├── notion-onboarding/
│   ├── SKILL.md                            # Workspace discovery workflow
│   └── references/
│       └── state-schema.md                 # ~/.config/notion/workspace.json schema
└── notion-cli-agent/
    ├── SKILL.md                            # Core CLI usage
    └── references/
        ├── filters.md                      # Property types × filter operators
        ├── batch-patterns.md               # Multi-op batch patterns
        └── workflows.md                    # Agent workflow recipes

Progressive disclosure

Skills load in three layers to keep context usage efficient:

The main SKILL.md for each skill is kept under 150 lines. Deep reference material lives in separate files that the agent reads only when that topic comes up.

Installation

# OpenClaw
cp -r skills/notion-cli-agent ~/.local/share/openclaw/skills/
cp -r skills/notion-onboarding ~/.local/share/openclaw/skills/

# See skills/README.md for other frameworks

---

🤝 Contributing

Contributions are welcome! Please open an issue first to discuss what you would like to change.

Releasing

The version in package.json, the CHANGELOG.md entry, the git tag, and the GitHub release are all cut before publishing. To publish a tagged version to npm:

git checkout main && git pull
git describe --tags --exact-match          # confirm you're on the release tag
npm publish                                # prepublishOnly runs the build

files in package.json limits the tarball to dist/, README.md, and LICENSE — npm pack --dry-run shows exactly what ships. Run pnpm test before publishing; there is no CI gate on publish.

---

📄 License

MIT © Balneario de Cofrentes - The largest longevity clinic in the world.

---

🙏 Acknowledgments

Built with:

• Commander.js — CLI framework
• Notion API — Official Notion API