pp-notion

What this skill does

<!-- 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.3 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

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

## 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, a