{"id":48109535,"url":"https://github.com/varanakonda/notion-cli","last_synced_at":"2026-04-04T16:01:22.366Z","repository":{"id":349149923,"uuid":"1201240164","full_name":"varanakonda/notion-cli","owner":"varanakonda","description":"C++23 Notion API client — 19 commands, BDD tests, AI agent support","archived":false,"fork":false,"pushed_at":"2026-04-04T14:28:36.000Z","size":739,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-04T14:31:40.001Z","etag":null,"topics":["ai-agent","cli","cmake","conan","cpp","cpp23","libcurl","notion","notion-api"],"latest_commit_sha":null,"homepage":"https://github.com/varanakonda/notion-cli#readme","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/varanakonda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-04T12:03:58.000Z","updated_at":"2026-04-04T14:28:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/varanakonda/notion-cli","commit_stats":null,"previous_names":["varanakonda/notion-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/varanakonda/notion-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varanakonda%2Fnotion-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varanakonda%2Fnotion-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varanakonda%2Fnotion-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varanakonda%2Fnotion-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/varanakonda","download_url":"https://codeload.github.com/varanakonda/notion-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varanakonda%2Fnotion-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31405197,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","cli","cmake","conan","cpp","cpp23","libcurl","notion","notion-api"],"created_at":"2026-04-04T16:00:36.290Z","updated_at":"2026-04-04T16:01:22.334Z","avatar_url":"https://github.com/varanakonda.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# notion-cli\n\n[![CI](https://github.com/varanakonda/notion-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/varanakonda/notion-cli/actions)\n[![C++23](https://img.shields.io/badge/C%2B%2B-23-blue.svg)](https://en.cppreference.com/w/cpp/23)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/varanakonda/notion-cli?label=Download)](https://github.com/varanakonda/notion-cli/releases/latest)\n\n**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.\n\n**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.\n\n\u003e **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.\n\nIf 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.\n\n## Download\n\nPre-built binaries for all platforms — no build tools needed:\n\n| Platform | Download |\n|----------|----------|\n| Linux (x86_64) | [notion-cli-linux-amd64](https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-linux-amd64) |\n| macOS (Apple Silicon) | [notion-cli-macos-arm64](https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-macos-arm64) |\n| Windows (x86_64) | [notion-cli-windows-amd64.exe](https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-windows-amd64.exe) |\n\n**Linux / macOS:**\n```bash\n# Download\ncurl -L https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-linux-amd64 -o notion-cli\nchmod +x notion-cli\n\n# Set your Notion token (get it at https://notion.so/profile/integrations)\nexport NOTION_INTERNAL_INTEGRATION_SECRET=\"ntn_...\"\n\n# Use\n./notion-cli me                                    # verify connection\n./notion-cli stats \u003cdatabase-id\u003e -g Status         # task breakdown\n./notion-cli find \u003cdatabase-id\u003e \"priority:Urgent\"  # smart query\n./notion-cli export db \u003cdatabase-id\u003e -o ./vault    # export to Obsidian\n\n# Optional: add to PATH\nsudo mv notion-cli /usr/local/bin/\n```\n\n**Windows (PowerShell):**\n```powershell\n# Download\nInvoke-WebRequest -Uri \"https://github.com/varanakonda/notion-cli/releases/latest/download/notion-cli-windows-amd64.exe\" -OutFile \"notion-cli.exe\"\n\n# Set your Notion token\n$env:NOTION_INTERNAL_INTEGRATION_SECRET = \"ntn_...\"\n\n# Use\n.\\notion-cli.exe me\n.\\notion-cli.exe stats \u003cdatabase-id\u003e -g Status\n```\n\nOr build from source — see [Build from Source](#build-from-source) below.\n\n---\n\n### Stats\n![Stats](docs/screenshots/stats.png)\n\n### Smart queries\n![Find](docs/screenshots/find.png)\n\n### Validation\n![Validate](docs/screenshots/validate.png)\n\n### JSON output (for AI agents / jq)\n![JSON](docs/screenshots/json.png)\n\n### Workspace tree\n![Tree](docs/screenshots/tree.png)\n\n## What is this?\n\n[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.\n\n**notion-cli** lets you do all of that without opening a browser:\n\n```bash\n# See your task breakdown at a glance\n$ notion-cli stats \u003cdatabase-id\u003e -g Status\nDatabase: 285 pages total\n\nBreakdown by Status:\n  Not started  256   89.8%  ###################################\n         Done   24    8.4%  ###\n  In progress    5    1.8%  \n\n# Find urgent tasks\n$ notion-cli find \u003cdatabase-id\u003e \"priority:Urgent\"\n7 results\n  [Not started] [Urgent] Setup CI/CD pipeline for staging\n  [Not started] [Urgent] Fix auth token refresh on mobile\n  [Not started] [Urgent] API rate limiting implementation\n  ...\n\n# Export entire database to Obsidian vault\n$ notion-cli export db \u003cdatabase-id\u003e -o ./vault\nExporting 285 pages...\nDone. 285 pages exported to ./vault\n\n# Check database health\n$ notion-cli validate \u003cdatabase-id\u003e\nTotal: 285, Errors: 0, Warnings: 5, Score: 100%\n\n# Inspect database schema (useful for AI agents)\n$ notion-cli inspect db \u003cdatabase-id\u003e\nDatabase: Tasks\nProperties (15):\n  Status (status) → [Not started, In progress, Done]\n  Priority (select) → [Urgent, High, Medium, Low]\n  Layer (multi_select) → [Backend, Frontend, DevOps, QA]\n  ...\n\n# Navigate workspace like a file tree\n$ notion-cli tree \u003croot-page-id\u003e -d 2\n[page] Engineering\n  [page] Plans\n  [page] ADR\n  [page] Architecture\n[page] Marketing\n[page] Personal\n[db] Tasks\n```\n\n## Why a CLI?\n\n**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.\n\n**For automation:** CI/CD pipelines, cron jobs, scripts. Update task status after deploy. Backup database nightly. Sync with Obsidian vault.\n\n**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.\n\n**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.\n\n## All Commands\n\n| Category | Commands | What it does |\n|----------|----------|-------------|\n| **Core** | `me` | Show connected bot info |\n| | `search \u003cquery\u003e` | Full-text search across workspace |\n| | `tree \u003cid\u003e [-d depth]` | Navigate pages like a filesystem |\n| **Pages** | `page get \u003cid\u003e` | Read page properties (JSON) |\n| | `page create \u003cparent\u003e \u003ctitle\u003e` | Create new page |\n| | `page update \u003cid\u003e \u003cjson\u003e` | Update properties |\n| | `page append \u003cid\u003e \u003cmarkdown\u003e` | Add content to page |\n| | `page archive/unarchive \u003cid\u003e` | Archive or restore |\n| **Databases** | `db get \u003cid\u003e` | Show schema |\n| | `db query \u003cid\u003e [-l limit]` | Query with pagination |\n| | `db list \u003cid\u003e` | List ALL pages (auto-paginate) |\n| | `db add \u003cid\u003e \u003cjson\u003e` | Create entry |\n| | `db create/update` | Schema management |\n| **Blocks** | `block list/get/update/delete` | Content block operations |\n| **Comments** | `comment list/add` | Page comments |\n| **Export** | `export page \u003cid\u003e -o dir` | Page → Markdown + YAML frontmatter |\n| | `export db \u003cid\u003e -o dir` | Entire database → Obsidian vault |\n| **Import** | `import file \u003cfile\u003e \u003cparent\u003e` | Markdown → Notion page |\n| | `import dir \u003cdir\u003e \u003cdb-id\u003e` | Folder of .md → database |\n| **Analytics** | `stats \u003cdb\u003e -g \u003cprop\u003e` | Breakdown with ASCII charts |\n| | `validate \u003cdb\u003e` | Health check: empties, dupes, score |\n| | `inspect db/page \u003cid\u003e` | Schema \u0026 content analysis |\n| **Bulk** | `find \u003cdb\u003e \u003cquery\u003e` | Smart filter: `status:Done priority:High` |\n| | `bulk update \u003cdb\u003e -w Status=X -s \u003cjson\u003e` | Mass update by filter |\n| | `bulk archive \u003cdb\u003e -w Status=X` | Mass archive |\n| | `batch --file ops.json` | Execute operation list from JSON |\n\n## Build from Source\n\n```bash\n# 1. Get your Notion token\n#    → https://www.notion.so/profile/integrations → New integration → Copy secret\n\n# 2. Set token\nexport NOTION_INTERNAL_INTEGRATION_SECRET=\"ntn_...\"\n\n# 3. Enable all capabilities for the integration\n#    → https://www.notion.so/profile/integrations → your integration → Capabilities\n#    → Enable: Read content, Update content, Insert content, Read comments, Insert comments\n\n# 4. Share pages with your integration\n#    → Open Notion page → ... menu → Add connections → Your integration\n\n# 4. Build\npip install conan\nconan install . --output-folder=build --build=missing\ncmake --preset conan-release\ncmake --build --preset conan-release\n\n# 5. Add to PATH (do once)\necho 'export PATH=\"/path/to/notion-cli/build/build/Release:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n\n# 6. Run\nnotion-cli me\n```\n\n### Alternative: build with Make\n\n```bash\nmake          # downloads nlohmann/json + CLI11 automatically\n./notion-cli me\n```\n\n## For AI Agents\n\nnotion-cli is designed to be called by AI agents (Claude, GPT, Cursor, etc.). Key features for agents:\n\n- **Structured output**: all commands return parseable text\n- **`inspect db`**: shows full schema so the agent knows what properties exist\n- **`find`**: natural filter syntax agents can construct: `status:Done priority:High`\n- **`batch --file`**: reduce tool calls — send multiple operations in one JSON file\n- **`export`**: dump workspace to files the agent can read without API calls\n- **`--help` on every subcommand**: agents can discover usage\n\nExample agent workflow:\n```bash\n# Agent inspects what's available\nnotion-cli inspect db \u003cid\u003e\n\n# Agent queries tasks\nnotion-cli find \u003cid\u003e \"status:In progress\"\n\n# Agent updates a task after completing work\nnotion-cli page update \u003cpage-id\u003e '{\"Status\":{\"status\":{\"name\":\"Done\"}}}'\n\n# Agent exports for offline analysis\nnotion-cli export db \u003cid\u003e -o /tmp/analysis\n```\n\n## Build Requirements\n\n- **C++23** compiler (GCC 14+, Clang 17+, MSVC 19.36+)\n- **CMake** 3.20+\n- **Conan 2** package manager (`pip install conan`)\n- **libcurl** with SSL\n\n### Dependencies\n\n| Library | Purpose | Managed by |\n|---------|---------|------------|\n| [nlohmann/json](https://github.com/nlohmann/json) | JSON serde | Conan |\n| [CLI11](https://github.com/CLIUtils/CLI11) | CLI parsing | Conan |\n| [Catch2](https://github.com/catchorg/Catch2) | BDD testing | Conan |\n| [libcurl](https://curl.se/) | HTTPS | System |\n\n## Testing\n\nBDD-style tests with Catch2 (SCENARIO / GIVEN / WHEN / THEN):\n\n```bash\n./build/build/Release/notion-cli-tests --reporter compact\n# All tests passed (96 assertions in 17 test cases)\n```\n\nCovers: dotenv parsing, JSON serde, markdown↔blocks, rich text, error handling, mock client for all command groups.\n\n## Architecture\n\n```\nsrc/\n  main.cpp          Entry point\n  client.hpp/cpp    Notion API client (std::expected error handling, pimpl)\n  types.hpp         Page, User, Paginated\u003cT\u003e with auto-serde\n  format.hpp/cpp    Markdown ↔ Notion blocks conversion\n  dotenv.hpp/cpp    .env file loader\n  print.hpp         io::println (std::format wrapper)\n  commands/         One .cpp per command group (19 commands total)\ntests/              Catch2 BDD tests\n```\n\n## Benchmarks vs notion-cli-agent (npm)\n\n| Metric | **notion-cli (C++)** | **notion-cli-agent (npm)** |\n|--------|---------------------|---------------------------|\n| Cold start | **610ms** | 2067ms (**3.4x slower**) |\n| Warm start | **380ms** | 541ms |\n| CPU time per call | **30ms** | 185ms (**6x more**) |\n| Binary size | **2.1 MB** | 642KB + Node.js (~100MB) |\n| Memory (RSS) | **~5 MB** | ~40 MB |\n| Dependencies | libcurl | Node.js runtime |\n| Install | Single binary | `npm install -g` |\n\nFull benchmark methodology: [docs/benchmarks.md](docs/benchmarks.md)\n\n## Credits\n\nInspired 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.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). TL;DR: fork → failing test → implement → PR.\n\n## Like it?\n\nIf notion-cli saves you time, consider:\n- Giving it a [star on GitHub](https://github.com/varanakonda/notion-cli) — helps others find it\n- 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\u0026title=notion-cli%20—%20Notion%20from%20the%20terminal%20(C%2B%2B23))\n- [Opening an issue](https://github.com/varanakonda/notion-cli/issues) if something doesn't work\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaranakonda%2Fnotion-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaranakonda%2Fnotion-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaranakonda%2Fnotion-cli/lists"}