notion-cli-agent

# notion-cli-agent

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

[![npm version](https://img.shields.io/npm/v/notion-cli-agent.svg)](https://www.npmjs.com/package/notion-cli-agent)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
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](https://agentskills.dev)-compatible skill files in the [`skills/`](./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`](./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
- **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
- **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)

```bash
npm install -g notion-cli-agent
```

### From source

```bash
# 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](https://www.notion.so/my-integrations))

---

## ⚙️ Configuration

### 1. Get your API token

1. Go to [notion.so/my-integrations](https://www.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

```bash
# 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

---

## 📖 Usage Guide

### Basic Commands

```bash
# 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>
```

---

## 🤖 AI Agent Features

### Smart Queries with `find`

Translate natural language into Notion filters:

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

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

```bash
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:

``

[truncated…]