Skip to content
Back to search

notion-cli-agent

Notion CLI with AI agent support. Smart queries, Obsidian sync, batch ops, backups, validation and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/balneario-de-cofrentes--notion-cli-agent/badge.svg)](/listings/balneario-de-cofrentes--notion-cli-agent)

HTML

<a href="/listings/balneario-de-cofrentes--notion-cli-agent"><img src="/api/listings/balneario-de-cofrentes--notion-cli-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

# Full quick reference (read this first)
notion quickstart

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 976 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # notion-cli-agent
  2. > The most powerful command-line interface for Notion — built for AI agents first, humans too.
  3. [![npm version](https://img.shields.io/npm/v/notion-cli-agent.svg)](https://www.npmjs.com/package/notion-cli-agent)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. 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.
  6. ---
  7. ## 🤖 For AI Agents
  8. ### Quick start
  9. ```bash
  10. npm install -g notion-cli-agent
  11. export NOTION_TOKEN="ntn_your_token_here"
  12. # Full quick reference (read this first)
  13. notion quickstart
  14. ```
  15. ### Agent Skills (recommended)
  16. 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.
  17. ```
  18. skills/
  19. ├── notion-onboarding/ ← run first: maps your workspace to a state file
  20. └── notion-cli-agent/ ← core CLI skill + references
  21. ```
  22. **Recommended setup for agents:**
  23. 1. Install skills in your agent framework (see [`skills/README.md`](./skills/README.md))
  24. 2. Run the **`notion-onboarding`** skill once — it discovers your databases (tasks, projects, OKRs, home page) and saves them to `~/.config/notion/workspace.json`
  25. 3. All subsequent tasks use the mapped IDs automatically — no more looking up database IDs
  26. ### Why a CLI over the Notion MCP/API?
  27. - **`--llm` mode** — compact, structured output optimized for agent consumption
  28. - **`notion find`** — natural language → Notion filters in one command
  29. - **`notion batch`** — multiple operations in a single shell call (minimize tool calls)
  30. - **`notion ai prompt`** — generates a database-specific prompt for the agent
  31. - **`notion inspect context`** — full schema + examples + command reference in one shot
  32. - No rate-limit boilerplate, no SDK setup, shell-composable
  33. ---
  34. ## ✨ Features
  35. ### Core Operations
  36. - **Search** — Find pages and databases across your workspace
  37. - **Pages** — Create, read, update, archive pages with full property support
  38. - **Databases** — Query with filters, create schemas, manage entries
  39. - **Blocks** — Add and manage page content (paragraphs, headings, lists, code, etc.)
  40. - **Comments** — Read and create comments on pages
  41. - **Files** — Upload images and attachments to pages, properties, icons/covers, and comments
  42. - **Users** — List workspace users and integrations
  43. ### 🤖 AI Agent Features
  44. - **Smart Queries** — Natural language queries translated to Notion filters
  45. - **Batch Operations** — Execute multiple operations in one command
  46. - **Agent Prompts** — Generate optimal prompts for AI agents to work with databases
  47. - **Summarize** — Get concise page summaries
  48. - **Extract** — Pull structured data from page content
  49. ### 🔄 Obsidian Integration
  50. - **Export to Obsidian** — Pages and databases with YAML frontmatter
  51. - **Import from Obsidian** — Import vault notes to Notion
  52. - **CSV & Markdown import** — Bulk import from files
  53. ### 📊 Analytics & Validation
  54. - **Statistics** — Database metrics, breakdowns by property
  55. - **Timeline** — Activity visualization over time
  56. - **Health Check** — Database integrity scoring
  57. - **Validation** — Find missing fields, overdue items, stale entries
  58. ### 🔗 Advanced Features
  59. - **Workspace Sync** — Cache databases locally, use names instead of UUIDs everywhere
  60. - **Templates** — Save and reuse page structures
  61. - **Backup** — Full database backup to JSON/Markdown
  62. - **Duplicate** — Clone pages and entire databases
  63. - **Relations** — Manage links, find backlinks, visualize graphs
  64. - **Bulk Operations** — Update or archive hundreds of entries at once
  65. ---
  66. ## 📦 Installation
  67. ### From npm (recommended)
  68. ```bash
  69. npm install -g notion-cli-agent
  70. ```
  71. ### From source
  72. ```bash
  73. # Clone the repository
  74. git clone https://github.com/Balneario-de-Cofrentes/notion-cli-agent.git
  75. cd notion-cli-agent
  76. # Install dependencies
  77. pnpm install
  78. # Build
  79. pnpm build
  80. # Link globally
  81. pnpm link --global
  82. ```
  83. ### Requirements
  84. - Node.js 22.12+
  85. - A Notion integration token ([create one here](https://www.notion.so/my-integrations))
  86. ---
  87. ## ⚙️ Configuration
  88. ### 1. Get your API token
  89. 1. Go to [notion.so/my-integrations](https://www.notion.so/my-integrations)
  90. 2. Click "New integration"
  91. 3. Give it a name and select capabilities
  92. 4. Copy the token (starts with `ntn_` or `secret_`)
  93. ### 2. Set the token
  94. ```bash
  95. # Option 1: Environment variable (recommended)
  96. export NOTION_TOKEN="ntn_your_token_here"
  97. # Option 2: Pass directly
  98. notion --token "ntn_xxx" search "query"
  99. ```
  100. ### 3. Share content with your integration
  101. **Important:** Your integration can only access pages explicitly shared with it.
  102. 1. Open any page or database in Notion
  103. 2. Click "..." menu → "Connect to" → Select your integration
  104. ---
  105. ## 🔄 Workspace Sync
  106. Sync your workspace to use database names instead of UUIDs:
  107. ```bash
  108. # Cache all accessible databases locally
  109. notion sync
  110. # List cached databases
  111. notion list
  112. notion list --json # For scripts
  113. notion list --ids-only # One ID per line
  114. # Now use names anywhere you'd use a database UUID
  115. notion db query "Tasks" --limit 5
  116. notion find "Tasks" "overdue assigned to me"
  117. notion validate health "Projects"
  118. notion stats overview "OKRs"
  119. ```
  120. 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.
  121. ---
  122. ## 📖 Usage Guide
  123. ### Basic Commands
  124. ```bash
  125. # Search across workspace
  126. notion search "project plan"
  127. notion search "meeting" --type page
  128. notion search "" --type database # List all databases
  129. # Exact lookup in a known database (deterministic)
  130. notion db query <db_id> --title "Known Page" --json
  131. # Filtered search (best-effort — Notion search is fuzzy)
  132. notion search "keyword" --db <db_id> --exact --first --json
  133. notion search "task" --db <db_id> # Filter by parent database
  134. # Get page info
  135. notion page get <page_id>
  136. notion page get <page_id> --content # Include blocks
  137. # Create page in database
  138. notion page create --parent <db_id> --title "New Task"
  139. notion page create --parent <db_id> --title "Bug Fix" \
  140. --prop "Status=Todo" \
  141. --prop "Priority=High"
  142. notion page create --parent <db_id> --title "Meeting Notes" --icon 📝
  143. # Update page
  144. notion page update <page_id> --prop "Status:status=Done"
  145. notion page update <page_id> --title "New Title"
  146. notion page update <page_id> --icon 🚀
  147. notion page update <page_id> --clear-prop "Assignee" # Type-aware clear
  148. # Archive page
  149. notion page archive <page_id>
  150. ```
  151. ### Output Formats
  152. ```bash
  153. # Export database as CSV
  154. notion db query <db_id> --csv > tasks.csv
  155. # Tab-separated (paste into spreadsheets)
  156. notion db query <db_id> --tsv | pbcopy
  157. # Just IDs for piping into other commands
  158. notion db query <db_id> --filter "Status=Done" --ids-only | \
  159. xargs -I {} notion page archive {}
  160. # Count search results
  161. notion search "bugs" --ids-only | wc -l
  162. ```
  163. | Flag | Commands | Description |
  164. |------|----------|-------------|
  165. | `--json` / `-j` | all | Raw JSON |
  166. | `--llm` | most | Compact agent-friendly output |
  167. | `--csv` | `db query`, `find` | CSV with headers |
  168. | `--tsv` | `db query`, `find` | Tab-separated |
  169. | `--ids-only` | `db query`, `search`, `find` | One ID per line |
  170. ---
  171. ## 📄 Page Content (read/write/edit)
  172. Read, write, and surgically edit page content as Markdown.
  173. ```bash
  174. # Read page content as Markdown (uses native Notion markdown API)
  175. notion page read <page_id>
  176. notion page read <page_id> --blocks # Legacy: fetch blocks and convert client-side
  177. notion page read <page_id> --json # Raw block JSON output
  178. notion page read <page_id> -o page.md # Write to file
  179. # Write Markdown content into a page
  180. notion page write <page_id> -f content.md
  181. echo "# Hello" | notion page write <page_id>
  182. notion page write <page_id> -f doc.md --replace # Replace all content (destructive)
  183. # Surgical block-level editing
  184. notion page edit <page_id> --at 3 --delete 2 # Delete 2 blocks at index 3
  185. notion page edit <page_id> --at 5 --markdown "New paragraph" # Insert at index 5
  186. notion page edit <page_id> --at 0 --delete 1 --file new.md # Replace first block
  187. notion page edit <page_id> --dry-run --at 3 --delete 1 # Preview without changes
  188. ```
  189. ---
  190. ## 📎 Files & Attachments
  191. Upload images and attachments to Notion. Anywhere a `<source>` 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.
  192. ```bash
  193. # Upload and attach in one call (block type detected from the file)
  194. notion file attach <page_id> shot.png
  195. notion file attach <page_id> a.pdf b.png --caption "Q3 report"
  196. notion file attach <page_id> clip.mp4 --as video --after <block_id>
  197. # Upload only — prints the file_upload ID for later use
  198. notion file upload shot.png # → ID: 1a2b3c4d-...
  199. notion file upload a.pdf b.png --json
  200. notion file import https://example.com/logo.png # Import from a public URL
  201. # Inspect uploads
  202. notion file list --status uploaded
  203. notion file get <file_upload_id>
  204. # Attach while adding content
  205. notion block append <page_id> --text "See below" --image shot.png --caption "Diagram"
  206. notion block append <page_id> --pdf report.pdf --file data.zip
  207. # Page icon, cover, and files properties
  208. notion page update <page_id> --icon logo.png --cover https://example.com/hero.jpg
  209. notion page update <page_id> --attach "Attachments=spec.pdf,diagram.png"
  210. notion page create --parent <db_id> -t "Release" --attach "Docs=notes.md"
  211. # Comments (max 3 attachments)
  212. notion comment create --page <page_id> -t "Screenshot attached" --attach shot.png
  213. ```
  214. `--icon` still takes an emoji (`--icon 📝`); anything that looks like a path, URL, or upload ID is uploaded instead.
  215. **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:
  216. ```bash
  217. notion file import https://images.unsplash.com/photo-1506744038136 --content-type image/jpeg
  218. notion page update <page_id> --cover <file_upload_id>
  219. ```
  220. ---
  221. ## 🤖 AI Agent Features
  222. ### Smart Queries with `find`
  223. Translate natural language into Notion filters:
  224. ```bash
  225. # Find overdue tasks
  226. notion find "overdue tasks" -d <db_id>
  227. # Find unassigned items in progress
  228. notion find "in progress unassigned" -d <db_id>
  229. # Find high priority pending items
  230. notion find "urgent pending" -d <db_id>
  231. # See what filter was generated
  232. notion find "tareas vencidas" -d <db_id> --explain
  233. ```
  234. **Supported patterns:**
  235. - Status: `done`, `in progress`, `todo`, `pending`, `hecho`, `en marcha`
  236. - Assignment: `unassigned`, `sin asignar`
  237. - Dates: `overdue`, `vencidas`, `today`, `this week`
  238. - Priority: `urgent`, `high priority`, `importante`
  239. ### Batch Operations
  240. Execute multiple operations in one command — perfect for AI agents to minimize tool calls:
  241. ```bash
  242. # Preview what would happen
  243. notion batch --dry-run --data '[
  244. {"op": "get", "type": "page", "id": "abc123"},
  245. {"op": "create", "type": "page", "parent": "db_id", "data": {...}},
  246. {"op": "update", "type": "page", "id": "xyz789", "data": {...}}
  247. ]'
  248. # Execute with LLM-friendly output
  249. notion batch --llm --data '[...]'
  250. # Read from file
  251. notion batch -f operations.json
  252. ```
  253. **Supported operations:**
  254. | Op | Types | Description |
  255. |----|-------|-------------|
  256. | `get` | page, database, block | Retrieve by ID |
  257. | `create` | page, database | Create new |
  258. | `update` | page, database, block | Modify |
  259. | `delete` | page, block | Archive/delete |
  260. | `query` | database | Query with filters |
  261. | `append` | block | Add children |
  262. ### Generate Agent Prompts
  263. Create optimal prompts for AI agents to work with a specific database:
  264. ```bash
  265. notion ai prompt <database_id>
  266. ```
  267. **Output includes:**
  268. - Database schema with all properties
  269. - Valid values for select/status fields (exact spelling matters!)
  270. - Example entries
  271. - Common operations with correct syntax
  272. - Warnings about property naming (e.g., "Title is called 'Título', not 'Name'")
  273. ### Summarize Pages
  274. Get concise summaries for quick understanding:
  275. ```bash
  276. notion ai summarize <page_id>
  277. # Output:
  278. # Project Plan Q1
  279. # Last edited: 2 days ago
  280. # Blocks: 45
  281. # Properties:
  282. # - Status: In Progress
  283. # - Owner: Juan
  284. # Sections:
  285. # - Overview
  286. # - Timeline
  287. # - Resources
  288. # Todos: 8/12 completed
  289. ```
  290. ### Extract Structured Data
  291. Pull specific data points from page content:
  292. ```bash
  293. notion ai extract <page_id> --schema "email,phone,company,date"
  294. # Output:
  295. {
  296. "email": "contact@example.com",
  297. "phone": "+34 612 345 678",
  298. "company": "Acme Corp",
  299. "date": "2024-03-15"
  300. }
  301. ```
  302. ### Command Suggestions
  303. Get command suggestions based on natural language:
  304. ```bash
  305. notion ai suggest <db_id> "quiero ver las tareas completadas esta semana"
  306. # Outputs:
  307. # notion find "hecho" -d <db_id>
  308. # notion db query <db_id> --filter-prop "Status" --filter-value "Hecho" --filter-prop-type status
  309. ```
  310. ---
  311. ## 🔄 Obsidian Integration
  312. ### Export to Obsidian
  313. **Export a single page:**
  314. ```bash
  315. notion export page <page_id> --obsidian -o my-note.md
  316. ```
  317. **Export entire database to vault:**
  318. ```bash
  319. notion export db <database_id> --vault ~/obsidian-vault --folder notion-tasks
  320. ```
  321. **With full page content:**
  322. ```bash
  323. notion export db <db_id> --vault ~/vault --content
  324. ```
  325. **Exported files include:**
  326. ```yaml
  327. ---
  328. notion_id: "abc123..."
  329. notion_url: "https://notion.so/..."
  330. created: 2024-01-15
  331. updated: 2024-02-01
  332. status: "In Progress"
  333. priority: "High"
  334. tags:
  335. - "project"
  336. - "q1"
  337. ---
  338. # Page Title
  339. Content here...
  340. ```
  341. ### Import from Obsidian
  342. **Import vault to database:**
  343. ```bash
  344. notion import obsidian ~/my-vault --to <database_id>
  345. notion import obsidian ~/my-vault --to <db_id> --folder specific-folder
  346. notion import obsidian ~/my-vault --to <db_id> --content # Include page content
  347. ```
  348. **Import CSV:**
  349. ```bash
  350. notion import csv data.csv --to <database_id>
  351. notion import csv tasks.csv --to <db_id> --title-column "Task Name"
  352. ```
  353. **Import Markdown file:**
  354. ```bash
  355. notion import markdown document.md --to <page_id>
  356. notion import markdown doc.md --to <page_id> --replace # Replace existing content
  357. ```
  358. ---
  359. ## 📊 Database Analytics
  360. ### Statistics Overview
  361. ```bash
  362. notion stats overview <database_id>
  363. # Output:
  364. # 📊 Database: Tasks
  365. # Total entries: 342
  366. #
  367. # Status:
  368. # Done 124 (36%) ████████
  369. # In Progress 89 (26%) ██████
  370. # Todo 78 (23%) █████
  371. # Blocked 51 (15%) ███
  372. #
  373. # Priority:
  374. # High 45 (13%) ███
  375. # Medium 187 (55%) ███████████
  376. # Low 110 (32%) ███████
  377. ```
  378. ### Activity Timeline
  379. ```bash
  380. notion stats timeline <database_id> --days 14
  381. # 2024-02-01 (Thu) 12 ████████████
  382. # 2024-01-31 (Wed) 8 ████████
  383. # 2024-01-30 (Tue) 15 ███████████████
  384. # ...
  385. ```
  386. ---
  387. ## ✅ Validation & Health
  388. ### Full Validation
  389. ```bash
  390. notion validate check <database_id> \
  391. --required "Assignee,Deadline" \
  392. --check-dates \
  393. --check-stale 30 \
  394. --fix
  395. # Output:
  396. # ⚠️ MISSING REQUIRED (23)
  397. # - Task ABC: Missing required property: Assignee
  398. # - Task XYZ: Missing required property: Deadline
  399. # Fix: notion page update <id> --prop "Assignee=..."
  400. #
  401. # ⚠️ OVERDUE (8)
  402. # - Old task: Overdue: deadline was 2024-01-15
  403. #
  404. # ℹ️ STALE (5)
  405. # - Stuck item: Not updated in 45 days (status: In Progress)
  406. #
  407. # 📊 Health Score: 72/100
  408. ```
  409. ### Quick Lint
  410. ```bash
  411. notion validate lint <database_id>
  412. # ✅ Empty titles: OK
  413. # ⚠️ "In Progress" for >30 days: 5 found
  414. # Total issues: 5
  415. ```
  416. ### Health Report
  417. ```bash
  418. notion validate health <database_id>
  419. # 📊 Health Report: Tasks
  420. # ════════════════════════════════════════
  421. # Health Score: 78/100 🟡
  422. # ════════════════════════════════════════
  423. #
  424. # 📈 Activity (last 7 days): 34/100 entries (34%)
  425. # ✅ Completion rate: 65%
  426. # 📝 Average fill rate: 82%
  427. #
  428. # Property fill rates:
  429. # ✅ Title ██████████ 100%
  430. # ✅ Status ██████████ 100%
  431. # ⚠️ Assignee ████████░░ 77%
  432. # ❌ Tags ██░░░░░░░░ 15%
  433. ```
  434. ---
  435. ## 💾 Backup & Restore
  436. ### Full Database Backup
  437. ```bash
  438. # Backup to JSON
  439. notion backup <database_id> -o ./backups/tasks
  440. # Backup to Markdown
  441. notion backup <db_id> -o ./backups --format markdown
  442. # Include page content
  443. notion backup <db_id> -o ./backups --content
  444. # Incremental backup (only changed entries)
  445. notion backup <db_id> -o ./backups --incremental
  446. ```
  447. **Output structure:**
  448. ```
  449. backups/
  450. ├── schema.json # Database schema
  451. ├── index.json # Entry index
  452. ├── .backup-meta.json # Backup metadata
  453. └── pages/
  454. ├── Task_One_abc123.json
  455. ├── Task_Two_def456.json
  456. └── ...
  457. ```
  458. ---
  459. ## 🧹 Dedup — Find & Clean Duplicates
  460. ```bash
  461. # Find duplicate pages by title
  462. notion dedup <db_id>
  463. # Include near-duplicates (strips copy/draft suffixes)
  464. notion dedup <db_id> --fuzzy
  465. # Archive duplicates, keep the page with most content
  466. notion dedup <db_id> --fix --strategy keep-largest --yes
  467. # Keep newest or oldest
  468. notion dedup <db_id> --fix --strategy keep-newest --yes
  469. notion dedup <db_id> --fix --strategy keep-oldest --yes
  470. # Preview first (default when --fix without --yes)
  471. notion dedup <db_id> --fix --strategy keep-largest
  472. ```
  473. ---
  474. ## 🔗 Relations & Backlinks
  475. ### Find Backlinks
  476. Discover what pages link to a specific page:
  477. ```bash
  478. notion relations backlinks <page_id>
  479. # 📎 Direct Relations:
  480. # Project Alpha
  481. # └─ via property: Related Tasks
  482. #
  483. # Sprint 23
  484. # └─ via property: Tasks
  485. #
  486. # 📝 Potential Mentions:
  487. # Meeting Notes Jan 15
  488. # Weekly Report
  489. ```
  490. ### Link/Unlink Pages
  491. ```bash
  492. # Create relation
  493. notion relations link <source_id> <target_id> --property "Related"
  494. # Bidirectional linking
  495. notion relations link <page1> <page2> --property "Related" --bidirectional
  496. # Remove relation
  497. notion relations unlink <source_id> <target_id> --property "Related"
  498. ```
  499. ### Visualize Relationship Graph
  500. ```bash
  501. # Text format
  502. notion relations graph <page_id> --depth 2
  503. # DOT format (for Graphviz)
  504. notion relations graph <page_id> --format dot > graph.dot
  505. dot -Tpng graph.dot -o graph.png
  506. # JSON format
  507. notion relations graph <page_id> --format json
  508. ```
  509. ---
  510. ## 📋 Templates
  511. ### Save a Page as Template
  512. ```bash
  513. notion template save <page_id> --name "weekly-report" --description "Weekly team report"
  514. ```
  515. ### List Templates
  516. ```bash
  517. notion template list
  518. # 📄 weekly-report
  519. # Blocks: 15
  520. # Description: Weekly team report
  521. #
  522. # 📄 meeting-notes
  523. # Blocks: 8
  524. ```
  525. ### Use Template
  526. ```bash
  527. notion template use "weekly-report" --parent <db_id> --title "Report Week 5"
  528. ```
  529. ### Manage Templates
  530. ```bash
  531. notion template show "weekly-report" # View details
  532. notion template delete "weekly-report" # Remove
  533. ```
  534. ---
  535. ## 🔄 Bulk Operations
  536. ### Bulk Update
  537. Update multiple entries at once:
  538. ```bash
  539. # Preview first
  540. notion bulk update <db_id> --where "Status=Todo" --set "Status=In Progress" --dry-run
  541. # Execute
  542. notion bulk update <db_id> --where "Status=Todo" --set "Status=In Progress" --yes
  543. ```
  544. ### Bulk Archive
  545. Archive entries matching a condition:
  546. ```bash
  547. # Archive completed items older than 2024
  548. notion bulk archive <db_id> --where "Status=Done" --dry-run
  549. notion bulk archive <db_id> --where "Status=Done" --yes
  550. ```
  551. **Where clause syntax:**
  552. - Equals: `Property=Value`
  553. - Multiple conditions: `Status=Done,Priority=Low`
  554. ---
  555. ## 🔍 Workspace Introspection
  556. ### List Accessible Databases
  557. ```bash
  558. notion inspect workspace
  559. notion inspect ws --compact # Just names and IDs
  560. ```
  561. ### Get Database Schema
  562. ```bash
  563. notion inspect schema <database_id>
  564. notion inspect schema <db_id> --llm # Optimized for AI consumption
  565. ```
  566. ### Generate Context for AI
  567. ```bash
  568. notion inspect context <database_id>
  569. # Outputs comprehensive context including:
  570. # - Schema with all properties and valid values
  571. # - Example entries
  572. # - Quick command reference
  573. ```
  574. ---
  575. ## 🔌 Raw API Access
  576. For operations not covered by other commands:
  577. ```bash
  578. # GET request
  579. notion api GET "pages/<page_id>"
  580. # POST with body
  581. notion api POST "search" --data '{"query": "test"}'
  582. # With query parameters
  583. notion api GET "users" --query "page_size=5"
  584. ```
  585. ---
  586. ## 📝 Property Formats
  587. When setting properties with `--prop`, the CLI auto-detects types:
  588. | Value Format | Detected Type | Example |
  589. |--------------|---------------|---------|
  590. | Plain text | select | `--prop "Status=Done"` |
  591. | `true`/`false` | checkbox | `--prop "Active=true"` |
  592. | Numbers | number | `--prop "Count=42"` |
  593. | `YYYY-MM-DD` | date | `--prop "Due=2024-12-31"` |
  594. | URL | url | `--prop "Link=https://..."` |
  595. | Email | email | `--prop "Contact=a@b.com"` |
  596. | Comma-separated | multi_select | `--prop "Tags=bug,urgent"` |
  597. **Type hints** — Force a specific property type with `Key:type=Value`:
  598. ```bash
  599. # Status properties (vs auto-detected select)
  600. notion page update <id> --prop "Status:status=Done"
  601. # Rich text instead of select
  602. notion page update <id> --prop "Notes:rich_text=Some notes"
  603. # People by user ID, email, or name
  604. notion page update <id> --prop "Assignee:people=user-id-here"
  605. notion page update <id> --prop "Assignee:people=ana@example.com" # resolved to id
  606. notion page update <id> --prop "Assignee:people=Ana Pérez" # case-insensitive name
  607. ```
  608. > **Assigning guests.** Notion's `GET /v1/users` (and `notion user list`) only
  609. > returns **members and bots** — guest users are invisible and you can't list
  610. > their id. Run `notion user resolve-guests` once: it discovers guests from
  611. > page authorship (`created_by`/`last_edited_by`) via `GET /v1/users/{id}` and
  612. > caches them in `~/.config/notion/guests.json`. After that, `notion user list`
  613. > shows them flagged `[guest]`, and `--prop "Field:people=<email|name>"`
  614. > resolves members (live list) and guests (cache) — exact email first, then
  615. > case-insensitive name. `notion sync` fishes guests too. Non-UUID values that
  616. > match nothing pass through unchanged.
  617. For database queries with non-select properties:
  618. ```bash
  619. notion db query <db_id> \
  620. --filter-prop "Status" \
  621. --filter-type equals \
  622. --filter-value "Done" \
  623. --filter-prop-type status # Required for status type
  624. ```
  625. ---
  626. ## 🔌 MCP Server Mode
  627. Run as an MCP tool server for agent frameworks (Claude Code, Cursor, VS Code):
  628. ```bash
  629. notion --mcp
  630. ```
  631. Configure in Claude Code (`settings.json`):
  632. ```json
  633. {
  634. "mcpServers": {
  635. "notion": {
  636. "command": "notion",
  637. "args": ["--mcp"],
  638. "env": { "NOTION_TOKEN": "ntn_your_token" }
  639. }
  640. }
  641. }
  642. ```
  643. 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`.
  644. ---
  645. ## 🎯 Command Reference
  646. | Category | Commands |
  647. |----------|----------|
  648. | **Search** | `search` |
  649. | **Pages** | `page get`, `page create`, `page update`, `page archive`, `page read`, `page write`, `page edit`, `page property` |
  650. | **Databases** | `db get`, `db query`, `db create`, `db update` |
  651. | **Blocks** | `block get`, `block list`, `block append`, `block update`, `block delete` |
  652. | **Comments** | `comment list`, `comment create`, `comment get` |
  653. | **Files** | `file upload`, `file import`, `file attach`, `file list`, `file get` |
  654. | **Users** | `user me`, `user list`, `user get`, `user resolve-guests` |
  655. | **Export** | `export page`, `export db` |
  656. | **Import** | `import obsidian`, `import csv`, `import markdown` |
  657. | **AI** | `ai summarize`, `ai extract`, `ai prompt`, `ai suggest` |
  658. | **Find** | `find` |
  659. | **Bulk** | `bulk update`, `bulk archive` |
  660. | **Validate** | `validate check`, `validate lint`, `validate health` |
  661. | **Stats** | `stats overview`, `stats timeline` |
  662. | **Backup** | `backup` |
  663. | **Templates** | `template list`, `template save`, `template use`, `template show`, `template delete` |
  664. | **Duplicate** | `duplicate page`, `duplicate schema`, `duplicate db` |
  665. | **Relations** | `relations backlinks`, `relations link`, `relations unlink`, `relations graph` |
  666. | **Inspect** | `inspect workspace`, `inspect schema`, `inspect context` |
  667. | **Dedup** | `dedup` |
  668. | **Batch** | `batch` |
  669. | **Quickstart** | `quickstart` |
  670. | **API** | `api` |
  671. ---
  672. ## 📦 Agent Skills
  673. The [`skills/`](./skills/) directory contains [AgentSkills](https://agentskills.dev)-compatible packages for use with OpenClaw, Claude Code, Cursor, and other agent frameworks.
  674. ### Structure
  675. ```
  676. skills/
  677. ├── README.md # Installation & overview
  678. ├── notion-onboarding/
  679. │ ├── SKILL.md # Workspace discovery workflow
  680. │ └── references/
  681. │ └── state-schema.md # ~/.config/notion/workspace.json schema
  682. └── notion-cli-agent/
  683. ├── SKILL.md # Core CLI usage
  684. └── references/
  685. ├── filters.md # Property types × filter operators
  686. ├── batch-patterns.md # Multi-op batch patterns
  687. └── workflows.md # Agent workflow recipes
  688. ```
  689. ### Progressive disclosure
  690. Skills load in three layers to keep context usage efficient:
  691. | Layer | Content | When loaded |
  692. |-------|---------|-------------|
  693. | Metadata | `name` + `description` | Always — triggers the skill |
  694. | Core | `SKILL.md` body | When skill activates |
  695. | Reference | `references/*.md` | On demand, as needed |
  696. 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.
  697. ### Installation
  698. ```bash
  699. # OpenClaw
  700. cp -r skills/notion-cli-agent ~/.local/share/openclaw/skills/
  701. cp -r skills/notion-onboarding ~/.local/share/openclaw/skills/
  702. # See skills/README.md for other frameworks
  703. ```
  704. ---
  705. ## 🤝 Contributing
  706. Contributions are welcome! Please open an issue first to discuss what you would like to change.
  707. ### Releasing
  708. 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:
  709. ```bash
  710. git checkout main && git pull
  711. git describe --tags --exact-match # confirm you're on the release tag
  712. npm publish # prepublishOnly runs the build
  713. ```
  714. `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.
  715. ---
  716. ## 📄 License
  717. MIT © [Balneario de Cofrentes](https://balneario.com) - The largest longevity clinic in the world.
  718. ---
  719. ## 🙏 Acknowledgments
  720. Built with:
  721. - [Commander.js](https://github.com/tj/commander.js) — CLI framework
  722. - [Notion API](https://developers.notion.com/) — Official Notion API

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.