Agent skill

Pp Notion

by mvanhorn in mvanhorn/printing-press-library

Notion CLI — manage pages and blocks, sync workspace to local SQLite, detect stale pages, and track changes.

Apache-2.0Auto-check: notesDatabases

Install Pp Notion

skills CLI
$ npx skills add mvanhorn/printing-press-library --skill pp-notion -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install mvanhorn/printing-press-library pp-notion --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/mvanhorn/printing-press-library.git skills-src && mkdir -p .claude/skills && cp -r skills-src/cli-skills/pp-notion .claude/skills/pp-notion && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
pp-notion
GitHub stars
2.1k
Token cost
~3.2k tokens
SKILL.md length
1,334 words
Files
1
Skills in repo
506
Repo updated
First seen
Licence
Apache-2.0

At a glance

Notion CLI — manage pages and blocks, sync workspace to local SQLite, detect stale pages, and track changes.

  • Works in 3 steps: Install via the Printing Press… → Verify: notion-pp-cli --version → Ensure the reported install directory is…
  • Phrases: find stale notion pages
  • SKILL.md covers Prerequisites: Install the CLI, When to Use This CLI, Unique Capabilities and Command Reference, plus 10 more sections
  • Calls go, claude and npx; needs NOTION_TOKEN

What it does

Pp Notion is an agent skill from mvanhorn/printing-press-library. Notion CLI — manage pages and blocks, sync workspace to local SQLite, detect stale pages, and track changes. Trigger phrases: find stale notion pages, sync notion to local, use notion-pp-cli, run notion, export notion page.

Its SKILL.md is about 3.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Databases. It works with Notion and SQLite. The repository describes itself as: Official library of CLIs generated by the CLI Printing Press. Endorsed, tested, and community-contributed. The licence is Apache-2.0.

When your agent uses it

  • Phrases: find stale notion pages
  • Sync notion to local
  • Use notion-pp-cli
  • Export notion page

Example prompts

  • “/pp-notion”

Requirements

  • Node.js
  • A credential in NOTION_TOKEN
  • Pre-approved tools (allowed-tools): Read, Bash

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and…
  2. Verify: notion-pp-cli --version
  3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

What it can do on your machine

Read from SKILL.md and the folder at commit 76de244. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Bash

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • go
    • claude
    • npx

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use npx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • NOTION_TOKEN

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Pp Notion loads about 3.2k tokens when it runs. Until then it costs about 61 tokens; SKILL.md has 1,334 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~61
When it runs · the whole SKILL.md, loaded when a task matches
~3.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from mvanhorn/printing-press-library at commit 76de244, republished under its Apache-2.0 licence (© mvanhorn). 1,334 words, ~3,192 tokens.

Download SKILL.mdSave it as .claude/skills/pp-notion/SKILL.md (or your agent's skills folder).
name
pp-notion
description
Notion CLI — manage pages and blocks, sync workspace to local SQLite, detect stale pages, and track changes. Trigger phrases: `find stale notion pages`, `sync notion to local`, `use notion-pp-cli`, `run notion`, `export notion page`.
allowed-tools
Read, Bash
author
Nikica Jokic
license
Apache-2.0
argument-hint
<command> [args] | install cli|mcp
<!-- 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):

bash
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.

    bash
    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.

    bash
    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
  • notion-pp-cli data-sources query post-database <data_source_id> — Query a data source. Note: the leaf command is post-database, not a bare query — data-sources query is an intermediate group that prints help. This differs from databases query <id>, which executes directly.

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:

bash
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
bash
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
bash
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
bash
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
bash
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.

Show full SKILL.md (567 more words)Show less

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:

bash
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:

    bash
    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

  • Explicit retries — use --idempotent only when an already-existing create should count as success, and --ignore-missing only when a missing delete target should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

notion-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
notion-pp-cli feedback --stdin < notes.txt
notion-pp-cli feedback list --json --limit 10

Entries are stored locally at ~/.notion-pp-cli/feedback.jsonl. They are never POSTed unless NOTION_FEEDBACK_ENDPOINT is set AND either --send is passed or NOTION_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

SinkEffect
stdoutDefault; write to stdout only
file:<path>Atomically write output to <path> (tmp + rename)
webhook:<url>POST the output body to the URL (application/json or application/x-ndjson when --compact)

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

notion-pp-cli profile save briefing --json
notion-pp-cli --profile briefing comments list --block-id 550e8400-e29b-41d4-a716-446655440000
notion-pp-cli profile list --json
notion-pp-cli profile show briefing
notion-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

CodeMeaning
0Success
2Usage error (wrong arguments)
3Resource not found
4Authentication required
5API error (upstream issue)
7Rate limited (wait and retry)
10Config error

Argument Parsing

Parse $ARGUMENTS:

  1. Empty, help, or --help → show notion-pp-cli --help output
  2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
  3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

  1. Install the MCP server:
    bash
    go install github.com/mvanhorn/printing-press-library/library/productivity/notion/cmd/notion-pp-mcp@latest
  2. Register with Claude Code:
    bash
    claude mcp add notion-pp-mcp -- notion-pp-mcp
  3. Verify: claude mcp list

Direct Use

  1. Check if installed: which notion-pp-cli If not found, offer to install (see Prerequisites at the top of this skill).
  2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
  3. Execute with the --agent flag:
    bash
    notion-pp-cli <command> [subcommand] [args] --agent
  4. If ambiguous, drill into subcommand help. Use notion-pp-cli <command> --help --agent when you need a machine-readable command/flag envelope; plain --help stays human-readable.

© mvanhorn, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in cli-skills/pp-notion of mvanhorn/printing-press-library.

Open the folder on GitHubat commit 76de244

Compare with similar skills

Pp Notion next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Pp Notion compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Pp Notion this skillmvanhorn/printing-press-library2.1k—~3.2kAutomated safety check: NotesApache-2.0
Iptvnator Sqlite DB Worker4gray/iptvnator7.3k—~824Automated safety check: PassMIT
Analyze Nsys Profilemlc-ai/pith-train355—~1.9kAutomated safety check: PassApache-2.0
Reactive Sqlite UIfastrepl/anarlog9.5k—~699Automated safety check: PassMIT
Composer Forensicsdxos/dxos525—~3.1kAutomated safety check: PassCustom licence
Sqlite Schema Designfastrepl/anarlog9.5k—~1.9kAutomated safety check: PassMIT

Similar skills

  • A skill your agent uses when changing Electron SQLite IPC, database-worker operations, request-scoped progress or cancellation, worker packaging, or runtime verification of non-EPG database work.

    7.3k GitHub stars~824 tokensUpdated today
    DatabasesAuto-check passed
  • Analyze Nsys Profile

    mlc-ai/pith-train

    Query a captured PithTrain Nsight Systems profile to measure compute/communication overlap, locate exposed comm by DualPipeV stage, and inspect per-rank stream behavior.

    355 GitHub stars~1.9k tokensUpdated 5 days ago
    DatabasesAuto-check passed
  • Reactive Sqlite UI

    fastrepl/anarlog

    Build SQLite-backed reactive UI in apps/desktop using stable patterns for reads, selection, forms, writes, and loading states.

    9.5k GitHub stars~699 tokensUpdated today
    DatabasesAuto-check passed
  • Forensically inspect and repair Composer browser profiles — offline (Chrome OPFS / SQLite extract) or live via /recovery.html debug port.

    525 GitHub stars~3.1k tokensUpdated today
    DatabasesAuto-check passed
  • Sqlite Schema Design

    fastrepl/anarlog

    Design or review schemas for crates/cloudsync using SQLite Sync constraints, not generic SQLite advice.

    9.5k GitHub stars~1.9k tokensUpdated today
    DatabasesAuto-check passed
  • Makemigrations

    deusXmachina-dev/memorylane

    Create SQLite migrations for MemoryLane storage schema changes.

    121 GitHub stars~973 tokensUpdated yesterday
    DatabasesAuto-check passed

More from mvanhorn/printing-press-library

All 506 skills in this repo
  • Agent Desktop

    mvanhorn/printing-press-library

    Desktop automation through the real Rust agent-desktop CLI, published in Printing Press through a small bridge.

    2.1k GitHub stars~2.3k tokensUpdated today
    Auto-check: notes
  • Gfonts

    mvanhorn/printing-press-library

    Search, browse, and download Google Fonts from the terminal via the gfonts CLI.

    2.1k GitHub stars~574 tokensUpdated today
    Auto-check passed
  • Pp 1688

    mvanhorn/printing-press-library

    The free, offline Trigger phrases: search 1688 for, find a factory on 1688 for, wholesale price on 1688 for, who is the cheapest supplier on 1688 for, compare 1688 suppliers for, use 1688, run 1688.

    2.1k GitHub stars~3k tokensUpdated today
    Auto-check: notes
  • Pp Activity Japan

    mvanhorn/printing-press-library

    Inspect known Activity Japan plan IDs or URLs, compare dated prices and sessions, check language-sitemap coverage, and hand off to canonical booking pages.

    2.1k GitHub stars~2k tokensUpdated today
    Auto-check: notes
  • Pp Adminbyrequest

    mvanhorn/printing-press-library

    Every Admin By Request portal action, plus a local SQLite mirror of audit, events, inventory and requests for ad-hoc...

    2.1k GitHub stars~3.3k tokensUpdated today
    Auto-check: notes
  • Pp Agent Capture

    mvanhorn/printing-press-library

    macOS screen capture, window recording, GIF conversion, and agent evidence bundles from the terminal.

    2.1k GitHub stars~1.6k tokensUpdated today
    Auto-check: notes

Works with

Categories

Questions about Pp Notion

What does Pp Notion do?

Notion CLI — manage pages and blocks, sync workspace to local SQLite, detect stale pages, and track changes. Pp Notion is an agent skill from mvanhorn/printing-press-library. Notion CLI — manage pages and blocks, sync workspace to local SQLite, detect stale pages, and track changes.

When should I use Pp Notion?

Pp Notion fits situations like: phrases: find stale notion pages; sync notion to local; use notion-pp-cli; export notion page.

How do I install Pp Notion in Claude Code?

Run `npx skills add mvanhorn/printing-press-library --skill pp-notion -a claude-code`. Or copy the skill folder (cli-skills/pp-notion in mvanhorn/printing-press-library) into .claude/skills/pp-notion in your project. Claude Code loads it when a task matches its description.

How do I install Pp Notion in Codex?

Run `npx skills add mvanhorn/printing-press-library --skill pp-notion -a codex`. Or copy the skill folder (cli-skills/pp-notion in mvanhorn/printing-press-library) into .agents/skills/pp-notion in your project. Codex loads it when a task matches its description.

Can I use Pp Notion in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add mvanhorn/printing-press-library --skill pp-notion -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/pp-notion, .gemini/skills/pp-notion, .github/skills/pp-notion and .opencode/skills/pp-notion in your project.

What does Pp Notion need to run?

Going by SKILL.md and its folder, Pp Notion needs the command-line tools its instructions call (go, claude and npx) and credentials named NOTION_TOKEN. Our summary lists: Node.js; A credential in NOTION_TOKEN. Its frontmatter pre-approves these tools: Read, Bash.

Does Pp Notion access the network?

SKILL.md contains no URLs. Its commands use npx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Pp Notion safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Pp Notion use?

Pp Notion is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Pp Notion use?

About 3.2k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Pp Notion?

Skills that share tags, products or a category with Pp Notion: Iptvnator Sqlite DB Worker (4gray/iptvnator, 7.3k stars), Analyze Nsys Profile (mlc-ai/pith-train, 355 stars), Reactive Sqlite UI (fastrepl/anarlog, 9.5k stars) and Composer Forensics (dxos/dxos, 525 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Pp Notion?

mvanhorn (a GitHub user) maintains it in mvanhorn/printing-press-library, which has 2,056 GitHub stars. The repository holds 506 skills in this directory. The repository was last updated on October 9, 2026.

Source: mvanhorn/printing-press-library on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.