Pp Notion

<!-- GENERATED FILE — DO NOT EDIT. This file is a verbatim mirror of library/productivity/notion/SKILL.md, regenerated post-merge by tools/generate-skills/. Hand-edits here are silently overwritten on the next regen. Edit the library/ source instead. See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Notion — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the notion-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows: ``bash npx -y @mvanhorn/printing-press-library install notion --cli-only ``
2. Verify: notion-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

go install github.com/mvanhorn/printing-press-library/library/productivity/notion/cmd/notion-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This CLI

Use notion-pp-cli when you need to manage Notion pages and blocks from the terminal, detect stale pages, or track what changed since a given time. Run sync once to populate the local store, then stale and changed work offline. Not a substitute for the Notion web UI for day-to-day editing.

Unique Capabilities

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

Command Reference

blocks — Block endpoints

• notion-pp-cli blocks delete — Delete a block
• notion-pp-cli blocks query-meeting-notes — Query meeting notes
• notion-pp-cli blocks get — Get a block by ID
• notion-pp-cli blocks update — Update a block
• notion-pp-cli blocks children list — List children of a block or page
• notion-pp-cli blocks children append — Append blocks to a page or 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 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 query <database_id> — Query records in a database with optional filter/sort
• 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 — 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 update — Update a page
• notion-pp-cli pages create — Create a page
• notion-pp-cli pages get — Get a page by ID
• notion-pp-cli pages move — Move a page
• notion-pp-cli pages markdown export — Export a page as markdown

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

sync pages — Sync all pages and databases to local SQLite

• notion-pp-cli sync pages — Sync all pages and databases via search API (run before stale/changed)
• notion-pp-cli sync pages --full — Full resync from scratch
• notion-pp-cli sync pages --type database — Sync databases only

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

notion-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes

Morning triage: what changed overnight

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

Show everything edited in the last 8 hours — use at session start to orient before taking action.

Find stale pages before cleanup

notion-pp-cli stale --days 30 --json --select id,title,days_since_edit,last_edited_time

Pages untouched for 30+ days, sorted oldest-first. The Notion UI has no equivalent filter across multiple workspaces.

Export a page as markdown

notion-pp-cli pages markdown export <page-id>

Fetches the page content as markdown via the native Notion markdown endpoint — no conversion needed.

Read block children of a page

notion-pp-cli blocks children list <page-id> --json --select id,type

List all top-level blocks on a page with their types and IDs.

Auth Setup

Requires a Notion Internal Integration token. Create one at notion.so/my-integrations, share your top-level pages with it, then set NOTION_BEARER_AUTH (or NOTION_TOKEN) in your environment.

First-run setup:

notion-pp-cli doctor          # verify auth
notion-pp-cli sync pages      # sync all pages + databases (~15k pages, takes 2-3 min)
notion-pp-cli stale --days 30 # now works
notion-pp-cli changed --since 24h

Run notion-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr
• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --agent --select id,name,status

• Previewable — --dry-run shows the request without sending
• Offline-friendly — sync/search commands can use the local SQLite store when available
• Non-interactive — never prompts, every input is a flag