https://github.com/varanakonda/notion-cli
C++23 Notion API client — 19 commands, BDD tests, AI agent support
https://github.com/varanakonda/notion-cli
ai-agent cli cmake conan cpp cpp23 libcurl notion notion-api
Last synced: 2 months ago
JSON representation
C++23 Notion API client — 19 commands, BDD tests, AI agent support
- Host: GitHub
- URL: https://github.com/varanakonda/notion-cli
- Owner: varanakonda
- License: mit
- Created: 2026-04-04T12:03:58.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-04-04T14:28:36.000Z (2 months ago)
- Last Synced: 2026-04-04T14:31:40.001Z (2 months ago)
- Topics: ai-agent, cli, cmake, conan, cpp, cpp23, libcurl, notion, notion-api
- Language: C++
- Homepage: https://github.com/varanakonda/notion-cli#readme
- Size: 722 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# notion-cli
[](https://github.com/varanakonda/notion-cli/actions)
[](https://en.cppreference.com/w/cpp/23)
[](LICENSE)
[](https://github.com/varanakonda/notion-cli/releases/latest)
**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](https://github.com/varanakonda/notion-cli) 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](https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-linux-amd64) |
| macOS (Apple Silicon) | [notion-cli-macos-arm64](https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-macos-arm64) |
| Windows (x86_64) | [notion-cli-windows-amd64.exe](https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-windows-amd64.exe) |
**Linux / macOS:**
```bash
# 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_..."
# Use
./notion-cli me # verify connection
./notion-cli stats -g Status # task breakdown
./notion-cli find "priority:Urgent" # smart query
./notion-cli export db -o ./vault # export to Obsidian
# Optional: add to PATH
sudo mv notion-cli /usr/local/bin/
```
**Windows (PowerShell):**
```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_..."
# Use
.\notion-cli.exe me
.\notion-cli.exe stats -g Status
```
Or build from source — see [Build from Source](#build-from-source) below.
---
### Stats
### Smart queries
### Validation
### JSON output (for AI agents / jq)
### Workspace tree
## What is this?
[Notion](https://notion.so) 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:
```bash
# See your task breakdown at a glance
$ notion-cli stats -g Status
Database: 285 pages total
Breakdown by Status:
Not started 256 89.8% ###################################
Done 24 8.4% ###
In progress 5 1.8%
# Find urgent tasks
$ notion-cli find "priority:Urgent"
7 results
[Not started] [Urgent] Setup CI/CD pipeline for staging
[Not started] [Urgent] Fix auth token refresh on mobile
[Not started] [Urgent] API rate limiting implementation
...
# Export entire database to Obsidian vault
$ notion-cli export db -o ./vault
Exporting 285 pages...
Done. 285 pages exported to ./vault
# Check database health
$ notion-cli validate
Total: 285, Errors: 0, Warnings: 5, Score: 100%
# Inspect database schema (useful for AI agents)
$ notion-cli inspect db
Database: Tasks
Properties (15):
Status (status) → [Not started, In progress, Done]
Priority (select) → [Urgent, High, Medium, Low]
Layer (multi_select) → [Backend, Frontend, DevOps, QA]
...
# Navigate workspace like a file tree
$ notion-cli tree -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?** Zero startup overhead. The binary launches instantly — no interpreter, no package loading, no VM warmup. On a cold start: ~1ms (C++) vs ~150ms (Node.js) vs ~50ms (Python). For a CLI you run hundreds of times a day, this adds up.
## All Commands
| Category | Commands | What it does |
|----------|----------|-------------|
| **Core** | `me` | Show connected bot info |
| | `search ` | Full-text search across workspace |
| | `tree [-d depth]` | Navigate pages like a filesystem |
| **Pages** | `page get ` | Read page properties (JSON) |
| | `page create ` | Create new page |
| | `page update ` | Update properties |
| | `page append ` | Add content to page |
| | `page archive/unarchive ` | Archive or restore |
| **Databases** | `db get ` | Show schema |
| | `db query [-l limit]` | Query with pagination |
| | `db list ` | List ALL pages (auto-paginate) |
| | `db add ` | 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 -o dir` | Page → Markdown + YAML frontmatter |
| | `export db -o dir` | Entire database → Obsidian vault |
| **Import** | `import file ` | Markdown → Notion page |
| | `import dir ` | Folder of .md → database |
| **Analytics** | `stats -g ` | Breakdown with ASCII charts |
| | `validate ` | Health check: empties, dupes, score |
| | `inspect db/page ` | Schema & content analysis |
| **Bulk** | `find ` | Smart filter: `status:Done priority:High` |
| | `bulk update -w Status=X -s ` | Mass update by filter |
| | `bulk archive -w Status=X` | Mass archive |
| | `batch --file ops.json` | Execute operation list from JSON |
## Build from Source
```bash
# 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
# 4. Build
pip install conan
conan install . --output-folder=build --build=missing
cmake --preset conan-release
cmake --build --preset conan-release
# 5. Add to PATH (do once)
echo 'export PATH="/path/to/notion-cli/build/build/Release:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 6. Run
notion-cli me
```
### Alternative: build with Make
```bash
make # downloads nlohmann/json + CLI11 automatically
./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:
```bash
# Agent inspects what's available
notion-cli inspect db
# Agent queries tasks
notion-cli find "status:In progress"
# Agent updates a task after completing work
notion-cli page update '{"Status":{"status":{"name":"Done"}}}'
# Agent exports for offline analysis
notion-cli export db -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](https://github.com/nlohmann/json) | JSON serde | Conan |
| [CLI11](https://github.com/CLIUtils/CLI11) | CLI parsing | Conan |
| [Catch2](https://github.com/catchorg/Catch2) | BDD testing | Conan |
| [libcurl](https://curl.se/) | HTTPS | System |
## Testing
BDD-style tests with Catch2 (SCENARIO / GIVEN / WHEN / THEN):
```bash
./build/build/Release/notion-cli-tests --reporter compact
# 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 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](docs/benchmarks.md)
## Credits
Inspired by [notion-cli-agent](https://github.com/Balneario-de-Cofrentes/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](CONTRIBUTING.md). TL;DR: fork → failing test → implement → PR.
## Like it?
If notion-cli saves you time, consider:
- Giving it a [star on GitHub](https://github.com/varanakonda/notion-cli) — helps others find it
- Sharing on [Twitter/X](https://twitter.com/intent/tweet?text=notion-cli%20%E2%80%94%20manage%20Notion%20from%20the%20terminal.%20Native%20C%2B%2B23%20binary%2C%2019%20commands%2C%20AI-agent%20ready.%20https%3A%2F%2Fgithub.com%2Fvaranakonda%2Fnotion-cli), [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/varanakonda/notion-cli), or [Reddit](https://www.reddit.com/submit?url=https://github.com/varanakonda/notion-cli&title=notion-cli%20—%20Notion%20from%20the%20terminal%20(C%2B%2B23))
- [Opening an issue](https://github.com/varanakonda/notion-cli/issues) if something doesn't work
## License
[MIT](LICENSE)