notion-cli

The problem: You use Notion for tasks, docs, and project management. Your AI agent (Claude, GPT, Cursor) needs to read and update your Notion workspace. But Notion MCP is slow (~2-5s per call), and raw REST API requires writing boilerplate for every operation.

The solution: A single native binary that gives your AI agent (or you) instant access to your entire Notion workspace. One command instead of 5 API calls. ~600ms cold start, ~30ms CPU per call. No Node.js, no Python, no runtime dependencies.

This is NOT an SDK or library. This is a CLI tool — you run it from the terminal, your AI agent runs it via shell, your CI/CD pipeline runs it in scripts. Think of it as git but for Notion.

If you find this useful, please give it a star and share with your network — it helps others discover this tool.

📥 Download

Pre-built binaries for all platforms — no build tools needed:

Platform	Download
Linux (x86_64)	notion-cli-linux-amd64
macOS (Apple Silicon)	notion-cli-macos-arm64
Windows (x86_64)	notion-cli-windows-amd64.exe

🐧 Linux / macOS:

Download:

curl -L https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-linux-amd64 -o notion-cli
chmod +x notion-cli

Set your Notion token (get it at https://notion.so/profile/integrations):

export NOTION_INTERNAL_INTEGRATION_SECRET="ntn_..."

Verify connection:

./notion-cli me

Task breakdown by status:

./notion-cli stats <database-id> -g Status

Find urgent tasks:

./notion-cli find <database-id> "priority:Urgent"

Export database to Obsidian vault:

./notion-cli export db <database-id> -o ./vault

Optional — add to PATH:

sudo mv notion-cli /usr/local/bin/

🪟 Windows (PowerShell):

Download:

Invoke-WebRequest -Uri "https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-windows-amd64.exe" -OutFile "notion-cli.exe"

Set your Notion token:

$env:NOTION_INTERNAL_INTEGRATION_SECRET = "ntn_..."

Verify connection:

.\notion-cli.exe me

Task breakdown by status:

.\notion-cli.exe stats <database-id> -g Status

Or build from source — see Build from Source below.

New to Notion + AI agents? Read the Vibe Coding with Notion guide — how to use Notion as persistent memory for Claude Code, Cursor, and Codex.

---

📊 Stats

🔍 Smart queries

✅ Validation

🔗 JSON output (for AI agents / jq)

🌳 Workspace tree

💡 What is this?

Notion is a popular workspace app for notes, tasks, and project management. Millions of developers use it to track issues, write docs, and plan sprints.

notion-cli lets you do all of that without opening a browser:

# See your task breakdown at a glance
$ notion-cli stats <database-id> -g Status
Database: 142 pages total

Breakdown by Status:
  Not started  98   69.0%  ###################################
         Done  31   21.8%  ###########
  In progress  13    9.2%  ####

# Find urgent tasks
$ notion-cli find <database-id> "priority:Urgent"
3 results
  [Not started] [Urgent] Deploy API to production
  [In progress] [Urgent] Fix payment webhook timeout
  [Not started] [Urgent] Update SSL certificates
  ...

# Export entire database to Obsidian vault
$ notion-cli export db <database-id> -o ./vault
Exporting 142 pages...
Done. 142 pages exported to ./vault

# Check database health
$ notion-cli validate <database-id>
Total: 142, Errors: 0, Warnings: 3, Score: 98%

# Inspect database schema (useful for AI agents)
$ notion-cli inspect db <database-id>
Database: Project Tasks
Properties (8):
  Status (status) → [Not started, In progress, Done]
  Priority (select) → [Urgent, High, Medium, Low]
  Assignee (people)
  ...

# Navigate workspace like a file tree
$ notion-cli tree <root-page-id> -d 2
[page] Engineering
  [page] Plans
  [page] ADR
  [page] Architecture
[page] Marketing
[page] Personal
[db] Tasks

🤔 Why a CLI?

For developers: You already live in the terminal. Switching to a browser to check tasks breaks flow. notion-cli stats is faster than loading Notion UI.

For automation: CI/CD pipelines, cron jobs, scripts. Update task status after deploy. Backup database nightly. Sync with Obsidian vault.

For AI agents: Claude, GPT, Cursor — any AI tool that can run shell commands can now read and write your Notion workspace. The structured output is designed for machine consumption.

Why C++ and not Node/Python? Minimal startup overhead. No interpreter, no package loading, no VM warmup. The binary itself launches in ~1ms — the rest is network I/O to Notion API. Node.js equivalent adds ~150ms just to start the runtime before any work begins.

📋 All Commands

Category	Commands	What it does
Core	me	Show connected bot info
	search <query>	Full-text search across workspace
	tree <id> [-d depth]	Navigate pages like a filesystem
Pages	page get <id>	Read page properties (JSON)
	page create <parent> <title>	Create new page
	page update <id> <json>	Update properties
	page append <id> <markdown>	Add content to page
	page archive/unarchive <id>	Archive or restore
Databases	db get <id>	Show schema
	db query <id> [-l limit]	Query with pagination
	db list <id>	List ALL pages (auto-paginate)
	db add <id> <json>	Create entry
	db create/update	Schema management
Blocks	block list/get/update/delete	Content block operations
Comments	comment list/add	Page comments
Export	export page <id> -o dir	Page → Markdown + YAML frontmatter
	export db <id> -o dir	Entire database → Obsidian vault
Import	import file <file> <parent>	Markdown → Notion page
	import dir <dir> <db-id>	Folder of .md → database
Analytics	stats <db> -g <prop>	Breakdown with ASCII charts
	validate <db>	Health check: empties, dupes, score
	inspect db/page <id>	Schema & content analysis
Bulk	find <db> <query>	Smart filter: status:Done priority:High
	bulk update <db> -w Status=X -s <json>	Mass update by filter
	bulk archive <db> -w Status=X	Mass archive
	batch --file ops.json	Execute operation list from JSON

🔧 Build from Source

1. Get your Notion token → https://www.notion.so/profile/integrations → New integration → Copy secret

2. Set token:

export NOTION_INTERNAL_INTEGRATION_SECRET="ntn_..."

3. Enable all capabilities for the integration:

https://www.notion.so/profile/integrations → your integration → Capabilities → Enable: Read content, Update content, Insert content, Read comments, Insert comments

4. Share pages with your integration:

Open Notion page → ... menu → Add connections → Your integration

5. Install Conan:

pip install conan

6. Build:

conan install . --output-folder=build --build=missing
cmake --preset conan-release
cmake --build --preset conan-release

7. Add to PATH (do once):

echo 'export PATH="/path/to/notion-cli/build/build/Release:$PATH"' >> ~/.bashrc
source ~/.bashrc

8. Run:

notion-cli me

Alternative: build with Make

make

./notion-cli me

🤖 For AI Agents

notion-cli is designed to be called by AI agents (Claude, GPT, Cursor, etc.). Key features for agents:

• Structured output: all commands return parseable text
• inspect db: shows full schema so the agent knows what properties exist
• find: natural filter syntax agents can construct: status:Done priority:High
• batch --file: reduce tool calls — send multiple operations in one JSON file
• export: dump workspace to files the agent can read without API calls
• --help on every subcommand: agents can discover usage

Example agent workflow:

Agent inspects what's available:

notion-cli inspect db <id>

Agent queries tasks:

notion-cli find <id> "status:In progress"

Agent updates a task after completing work:

notion-cli page update <page-id> '{"Status":{"status":{"name":"Done"}}}'

Agent exports for offline analysis:

notion-cli export db <id> -o /tmp/analysis

📦 Build Requirements

• C++23 compiler (GCC 14+, Clang 17+, MSVC 19.36+)
• CMake 3.20+
• Conan 2 package manager (pip install conan)
• libcurl with SSL

Dependencies

Library	Purpose	Managed by
nlohmann/json	JSON serde	Conan
CLI11	CLI parsing	Conan
Catch2	BDD testing	Conan
libcurl	HTTPS	System

🧪 Testing

BDD-style tests with Catch2 (SCENARIO / GIVEN / WHEN / THEN):

./build/build/Release/notion-cli-tests --reporter compact

Expected output: All tests passed (96 assertions in 17 test cases)

Covers: dotenv parsing, JSON serde, markdown↔blocks, rich text, error handling, mock client for all command groups.

🏗️ Architecture

src/
  main.cpp          Entry point
  client.hpp/cpp    Notion API client (std::expected error handling, pimpl)
  types.hpp         Page, User, Paginated<T> with auto-serde
  format.hpp/cpp    Markdown ↔ Notion blocks conversion
  dotenv.hpp/cpp    .env file loader
  print.hpp         io::println (std::format wrapper)
  commands/         One .cpp per command group (19 commands total)
tests/              Catch2 BDD tests

⚡ Benchmarks vs notion-cli-agent (npm)

Metric	notion-cli (C++)	notion-cli-agent (npm)
Cold start	610ms	2067ms (3.4x slower)
Warm start	380ms	541ms
CPU time per call	30ms	185ms (6x more)
Binary size	2.1 MB	642KB + Node.js (~100MB)
Memory (RSS)	~5 MB	~40 MB
Dependencies	libcurl	Node.js runtime
Install	Single binary	npm install -g

Full benchmark methodology: docs/benchmarks.md

🙏 Credits

Inspired by notion-cli-agent — a TypeScript/npm Notion CLI with AI agent support. This project is a native C++23 reimplementation targeting the same feature set with lower overhead.

🤝 Contributing

See CONTRIBUTING.md. TL;DR: fork → failing test → implement → PR.

⭐ Like it?

If notion-cli saves you time, consider:

• Giving it a star on GitHub — helps others find it
• Sharing on Twitter/X, LinkedIn, or Reddit
• Opening an issue if something doesn't work

📄 License

MIT