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:

Install skills in your agent framework (see skills/README.md)
Run the notion-onboarding skill once — it discovers your databases (tasks, projects, OKRs, home page) and saves them to ~/.config/notion/workspace.json
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
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

Go to notion.so/my-integrations
Click "New integration"
Give it a name and select capabilities
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.

Open any page or database in Notion
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 <db_id> --title "Known Page" --json

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

# Get page info
notion page get <page_id>
notion page get <page_id> --content  # Include blocks

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

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

# Archive page
notion page archive <page_id>

Output Formats

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

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

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

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

Flag	Commands	Description
`--json` / `-j`	all	Raw JSON
`--llm`	most	Compact agent-friendly output
`--csv`	`db query`, `find`	CSV with headers
`--tsv`	`db query`, `find`	Tab-separated
`--ids-only`	`db query`, `search`, `find`	One ID per line

📄 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 <page_id>
notion page read <page_id> --blocks        # Legacy: fetch blocks and convert client-side
notion page read <page_id> --json          # Raw block JSON output
notion page read <page_id> -o page.md      # Write to file

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

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

🤖 AI Agent Features

Smart Queries with `find`

Translate natural language into Notion filters:

# Find overdue tasks
notion find "overdue tasks" -d <db_id>

# Find unassigned items in progress
notion find "in progress unassigned" -d <db_id>

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

# See what filter was generated
notion find "tareas vencidas" -d <db_id> --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:

Op	Types	Description
`get`	page, database, block	Retrieve by ID
`create`	page, database	Create new
`update`	page, database, block	Modify
`delete`	page, block	Archive/delete
`query`	database	Query with filters
`append`	block	Add children

Generate Agent Prompts

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

notion ai prompt <database_id>

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 <page_id>

# 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 <page_id> --schema "email,phone,company,date"

# Output:
{
  "email": "contact@example.com",
  "phone": "+34 612 345 678",
  "company": "Acme Corp",
  "date": "2024-03-15"
}

Command Suggestions

Get command suggestions based on natural language:

notion ai suggest <db_id> "quiero ver las tareas completadas esta semana"

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

🔄 Obsidian Integration

Export to Obsidian

Export a single page:

notion export page <page_id> --obsidian -o my-note.md

Export entire database to vault:

notion export db <database_id> --vault ~/obsidian-vault --folder notion-tasks

With full page content:

notion export db <db_id> --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 <database_id>
notion import obsidian ~/my-vault --to <db_id> --folder specific-folder
notion import obsidian ~/my-vault --to <db_id> --content  # Include page content

Import CSV:

notion import csv data.csv --to <database_id>
notion import csv tasks.csv --to <db_id> --title-column "Task Name"

Import Markdown file:

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

📊 Database Analytics

Statistics Overview

notion stats overview <database_id>

# 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 <database_id> --days 14

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

✅ Validation & Health

Full Validation

notion validate check <database_id> \
  --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 <id> --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 <database_id>

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

Health Report

notion validate health <database_id>

# 📊 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 <database_id> -o ./backups/tasks

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

# Include page content
notion backup <db_id> -o ./backups --content

# Incremental backup (only changed entries)
notion backup <db_id> -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 <db_id>

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

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

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

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

🔗 Relations & Backlinks

Find Backlinks

Discover what pages link to a specific page:

notion relations backlinks <page_id>

# 📎 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 <source_id> <target_id> --property "Related"

# Bidirectional linking
notion relations link <page1> <page2> --property "Related" --bidirectional

# Remove relation
notion relations unlink <source_id> <target_id> --property "Related"

Visualize Relationship Graph

# Text format
notion relations graph <page_id> --depth 2

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

# JSON format
notion relations graph <page_id> --format json

📋 Templates

Save a Page as Template

notion template save <page_id> --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 <db_id> --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 <db_id> --where "Status=Todo" --set "Status=In Progress" --dry-run

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

Bulk Archive

Archive entries matching a condition:

# Archive completed items older than 2024
notion bulk archive <db_id> --where "Status=Done" --dry-run
notion bulk archive <db_id> --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 <database_id>
notion inspect schema <db_id> --llm  # Optimized for AI consumption

Generate Context for AI

notion inspect context <database_id>

# 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/<page_id>"

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

Value Format	Detected Type	Example
Plain text	select	`--prop "Status=Done"`
`true`/`false`	checkbox	`--prop "Active=true"`
Numbers	number	`--prop "Count=42"`
`YYYY-MM-DD`	date	`--prop "Due=2024-12-31"`
URL	url	`--prop "Link=https://..."`
Email	email	`--prop "Contact=a@b.com"`
Comma-separated	multi_select	`--prop "Tags=bug,urgent"`

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

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

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

# People by user ID
notion page update <id> --prop "Assignee:people=user-id-here"

For database queries with non-select properties:

notion db query <db_id> \
  --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

Category	Commands
Search	`search`
Pages	`page get`, `page create`, `page update`, `page archive`, `page read`, `page write`, `page edit`, `page property`
Databases	`db get`, `db query`, `db create`, `db update`
Blocks	`block get`, `block list`, `block append`, `block update`, `block delete`
Comments	`comment list`, `comment create`, `comment get`
Users	`user me`, `user list`, `user get`
Export	`export page`, `export db`
Import	`import obsidian`, `import csv`, `import markdown`
AI	`ai summarize`, `ai extract`, `ai prompt`, `ai suggest`
Find	`find`
Bulk	`bulk update`, `bulk archive`
Validate	`validate check`, `validate lint`, `validate health`
Stats	`stats overview`, `stats timeline`
Backup	`backup`
Templates	`template list`, `template save`, `template use`, `template show`, `template delete`
Duplicate	`duplicate page`, `duplicate schema`, `duplicate db`
Relations	`relations backlinks`, `relations link`, `relations unlink`, `relations graph`
Inspect	`inspect workspace`, `inspect schema`, `inspect context`
Dedup	`dedup`
Batch	`batch`
Quickstart	`quickstart`
API	`api`

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

Layer	Content	When loaded
Metadata	`name` + `description`	Always — triggers the skill
Core	`SKILL.md` body	When skill activates
Reference	`references/*.md`	On demand, as needed

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.

📄 License

🙏 Acknowledgments

Built with:

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

notion-cli-agent

Description

README

notion-cli-agent

🤖 For AI Agents

Quick start

Agent Skills (recommended)

Why a CLI over the Notion MCP/API?

✨ Features

Core Operations

🤖 AI Agent Features

🔄 Obsidian Integration

📊 Analytics & Validation

🔗 Advanced Features

📦 Installation

From npm (recommended)

From source

Requirements

⚙️ Configuration

1. Get your API token

2. Set the token

3. Share content with your integration

🔄 Workspace Sync

📖 Usage Guide

Basic Commands

Output Formats

📄 Page Content (read/write/edit)

🤖 AI Agent Features

Smart Queries with find

Batch Operations

Generate Agent Prompts

Summarize Pages

Extract Structured Data

Command Suggestions

🔄 Obsidian Integration

Export to Obsidian

Import from Obsidian

📊 Database Analytics

Statistics Overview

Activity Timeline

✅ Validation & Health

Full Validation

Quick Lint

Health Report

💾 Backup & Restore

Full Database Backup

🧹 Dedup — Find & Clean Duplicates

🔗 Relations & Backlinks

Find Backlinks

Link/Unlink Pages

Visualize Relationship Graph

📋 Templates

Save a Page as Template

List Templates

Use Template

Manage Templates

🔄 Bulk Operations

Bulk Update

Bulk Archive

🔍 Workspace Introspection

List Accessible Databases

Get Database Schema

Generate Context for AI

🔌 Raw API Access

📝 Property Formats

🔌 MCP Server Mode

🎯 Command Reference

📦 Agent Skills

Structure

Progressive disclosure

Installation

🤝 Contributing

📄 License

🙏 Acknowledgments

Release History

Dependencies & License Audit

Similar Packages

Smart Queries with `find`