Notion CLI

Every Notion database queryable offline — cross-workspace SQL joins, stale detection, and relation graph traversal the UI can never give you.

notion-pp-cli syncs your Notion workspace into a local SQLite store and exposes commands that answer compound questions the Notion UI cannot: cross-database joins, status drift, dead links, workspace health, and who owns what across every client. Works offline and ships a full MCP server so agents can load rich project context in a single call instead of 30.

Created by @neektza (Nikica Jokic).

Authentication

Requires a Notion Internal Integration token. Create one at notion.so/my-integrations, then share your databases with it. Set NOTION_TOKEN in your environment. Run notion-pp-cli sync once to populate the local store.

Quick Start

# Paste your NOTION_TOKEN from notion.so/my-integrations
notion-pp-cli auth set-token

# Mirror your entire workspace to local SQLite — takes 30-120 seconds depending on workspace size
notion-pp-cli sync --full

# Find everything untouched for 30+ days
notion-pp-cli stale --days 30 --json

# Get a hygiene scorecard for the whole workspace
notion-pp-cli workspace-health

# Raw SQL against the local store for custom queries
notion-pp-cli sql "SELECT title, last_edited_time FROM pages ORDER BY last_edited_time DESC LIMIT 20" --agent

Unique Features

These capabilities aren't available in any other tool for this API.

Agent-native plumbing

• changed — Show everything in the workspace added, edited, or deleted since your last sync or a given timestamp.

  Use at the start of an agent session to orient on what has changed before taking action.

  notion-pp-cli changed --since 2h --json
  

Local state that compounds

• stale — List pages and records not edited in N days, filterable by database, parent, or tag.

  Use to identify dead pages before workspace cleanup or to flag deliverables overdue for review.

  notion-pp-cli stale --days 30 --db ProjectDB --agent
  

Usage

Run notion-pp-cli --help for the full command reference and flag list.

Commands

blocks

Block endpoints

• notion-pp-cli blocks delete-a - Delete a block
• notion-pp-cli blocks query-meeting-notes - Query meeting notes
• notion-pp-cli blocks retrieve-a - Retrieve a block
• notion-pp-cli blocks update-a - Update a block

comments

Comment endpoints

• notion-pp-cli comments create-a - Create a comment
• notion-pp-cli comments delete-a - Delete a comment
• notion-pp-cli comments list - List comments
• notion-pp-cli comments retrieve - Retrieve a comment
• notion-pp-cli comments update-a - Update a comment

custom-emojis

Custom emoji endpoints

• notion-pp-cli custom-emojis list - List custom emojis

data-sources

Data source endpoints

• notion-pp-cli data-sources create-a-database - Create a data source
• notion-pp-cli data-sources retrieve-a - Retrieve a data source
• notion-pp-cli data-sources update-a - Update a data source

databases

Database endpoints

• notion-pp-cli databases create - Create a database
• notion-pp-cli databases retrieve - Retrieve a database
• notion-pp-cli databases update - Update a database

file-uploads

File upload endpoints

• notion-pp-cli file-uploads create-file - Create a file upload
• notion-pp-cli file-uploads list - List file uploads
• notion-pp-cli file-uploads retrieve - Retrieve a file upload

notion-search

Manage notion search

• notion-pp-cli notion-search post - Search by title

oauth

OAuth endpoints (basic authentication)

• notion-pp-cli oauth create-a-token - Exchange an authorization code for an access and refresh token
• notion-pp-cli oauth introspect-token - Introspect a token
• notion-pp-cli oauth revoke-token - Revoke a token

pages

Page endpoints

• notion-pp-cli pages patch - Update page
• notion-pp-cli pages post - Create a page
• notion-pp-cli pages retrieve-a - Retrieve a page

users

User endpoints

• notion-pp-cli users get - List all users
• notion-pp-cli users get-self - Retrieve your token's bot user
• notion-pp-cli users get-userid - Retrieve a user

views

View endpoints

• notion-pp-cli views create - Create a view
• notion-pp-cli views delete - Delete a view
• notion-pp-cli views list - List views
• notion-pp-cli views retrieve-a - Retrieve a view
• notion-pp-cli views update-a - Update a view

Output Formats

# Human-readable table (default in terminal, JSON when piped)
notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000

# JSON for scripting and agents
notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --json

# Filter to specific fields
notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --json --select id,name,status

# Dry run — show the request without sending
notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --dry-run

# Agent mode — JSON + compact + no prompts in one flag
notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

notion-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/notion-pp-cli/config.toml

Environment variables:

Name	Kind	Required	Description
NOTION_BEARER_AUTH	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

• Run notion-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $NOTION_BEARER_AUTH Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• sync returns 'object not found' for some databases — Share those databases with your integration at notion.so/my-integrations — the token only sees what you've explicitly shared
• stale/cross-db query returns empty results — Run notion-pp-cli sync --full first to populate the local store
• NOTION_TOKEN not recognized — Token format is ntn_... for internal integrations — do not use your Notion account password or OAuth tokens

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• notion-sdk-js — TypeScript (5598 stars)
• notion-mcp-server (official) — TypeScript (4307 stars)
• notion-sdk-py — Python (2171 stars)
• mcp-notion-server (suekou) — TypeScript (887 stars)
• notion2md — Python (758 stars)
• notionapi (Go) — Go (574 stars)
• notion-cli (4ier) — Go (192 stars)
• notion-cli (kris-hansen) — Python (132 stars)

Generated by CLI Printing Press