Productivity

Notion

pp-notion

Every Notion database queryable offline — cross-workspace SQL joins, stale detection, and relation graph traversal...

Printed by @neektza (Nikica Jokic)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install notion

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-notion --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-notion skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-notion. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

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.

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

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