pp-notion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Notion — Printing Press CLI

Notion —— Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装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:

Install via the Printing Press installer:

bash

npx -y @mvanhorn/printing-press install notion --cli-only

Verify:
```
notion-pp-cli --version
```
Ensure
```
$GOPATH/bin
```
(or
```
$HOME/go/bin
```
) is on
```
$PATH
```
.

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

--version

reports "command not found" after install, the install step did not put the binary on

$PATH

. Do not proceed with skill commands until verification succeeds.

notion-pp-cli syncs your Notion workspace into a local SQLite store and exposes commands for page and block management, stale page detection, and change tracking. Works offline and ships a full MCP server.

本技能基于

notion-pp-cli

二进制文件运行。在调用本技能的任何命令前，必须先验证CLI已安装。若未安装，请先执行以下步骤：

通过Printing Press安装器安装：

bash

npx -y @mvanhorn/printing-press install notion --cli-only

验证安装：
```
notion-pp-cli --version
```
确保
```
$GOPATH/bin
```
（或
```
$HOME/go/bin
```
）已添加到
```
$PATH
```
环境变量中。

若

npx

安装失败（无Node环境、离线等情况），可改用Go直接安装（要求Go 1.26.3或更高版本）：

bash

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

若安装后执行

--version

提示“command not found”，说明安装程序未将二进制文件添加到

$PATH

中。请在验证成功前不要执行技能命令。

notion-pp-cli可将你的Notion工作区同步到本地SQLite存储，并提供页面与区块管理、陈旧页面检测、变更追踪等命令。支持离线使用，且内置完整MCP服务器。

When to Use This CLI

何时使用该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.

当你需要从终端管理Notion页面与区块、检测陈旧页面，或追踪指定时间点后的变更时，可使用notion-pp-cli。先执行

sync

命令填充本地存储，之后

stale

和

changed

命令即可离线运行。本工具无法替代Notion网页UI用于日常编辑。

Unique Capabilities

独特功能

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

这些功能是其他同类型API工具所不具备的。

Agent-native plumbing

原生Agent适配能力

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
```

changed
—— 显示自上次同步或指定时间戳以来，工作区中新增、编辑或删除的所有内容。
可在Agent会话开始前使用，帮助了解变更情况后再执行操作。
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
```

stale
—— 列出N天内未编辑的页面和记录，可按数据库、父页面或标签筛选。
用于在清理工作区前识别废弃页面，或标记逾期待审核的交付物。
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

blocks —— 区块相关端点

```
notion-pp-cli blocks delete
```
—— 删除区块

notion-pp-cli blocks query-meeting-notes

—— 查询会议笔记

```
notion-pp-cli blocks get
```
—— 通过ID获取区块
```
notion-pp-cli blocks update
```
—— 更新区块
```
notion-pp-cli blocks children list
```
—— 列出区块或页面的子元素
```
notion-pp-cli blocks children append
```
—— 向页面或区块添加子元素

comments —— 评论相关端点

```
notion-pp-cli comments create-a
```
—— 创建评论
```
notion-pp-cli comments delete-a
```
—— 删除评论
```
notion-pp-cli comments list
```
—— 列出评论
```
notion-pp-cli comments retrieve
```
—— 获取评论
```
notion-pp-cli comments update-a
```
—— 更新评论

custom-emojis —— 自定义表情相关端点

```
notion-pp-cli custom-emojis
```
—— 列出自定义表情

data-sources —— 数据源相关端点

notion-pp-cli data-sources create-a-database

—— 创建数据源

```
notion-pp-cli data-sources retrieve-a
```
—— 获取数据源
```
notion-pp-cli data-sources update-a
```
—— 更新数据源

databases —— 数据库相关端点

```
notion-pp-cli databases query <database_id>
```
—— 查询数据库中的记录，可添加筛选/排序条件
```
notion-pp-cli databases create
```
—— 创建数据库
```
notion-pp-cli databases retrieve
```
—— 获取数据库
```
notion-pp-cli databases update
```
—— 更新数据库

file-uploads —— 文件上传相关端点

```
notion-pp-cli file-uploads create-file
```
—— 创建文件上传
```
notion-pp-cli file-uploads list
```
—— 列出文件上传记录
```
notion-pp-cli file-uploads retrieve
```
—— 获取文件上传记录

notion-search —— 管理Notion搜索

```
notion-pp-cli notion-search
```
—— 按标题搜索

oauth —— OAuth相关端点（基础认证）

```
notion-pp-cli oauth create-a-token
```
—— 用授权码交换访问令牌和刷新令牌
```
notion-pp-cli oauth introspect-token
```
—— 检查令牌状态
```
notion-pp-cli oauth revoke-token
```
—— 撤销令牌

pages —— 页面相关端点

```
notion-pp-cli pages update
```
—— 更新页面
```
notion-pp-cli pages create
```
—— 创建页面
```
notion-pp-cli pages get
```
—— 通过ID获取页面
```
notion-pp-cli pages move
```
—— 移动页面
```
notion-pp-cli pages markdown export
```
—— 将页面导出为Markdown格式

users —— 用户相关端点

```
notion-pp-cli users get
```
—— 列出所有用户
```
notion-pp-cli users get-self
```
—— 获取当前令牌对应的机器人用户
```
notion-pp-cli users get-userid
```
—— 获取指定用户

views —— 视图相关端点

```
notion-pp-cli views create
```
—— 创建视图
```
notion-pp-cli views delete
```
—— 删除视图
```
notion-pp-cli views list
```
—— 列出视图
```
notion-pp-cli views retrieve-a
```
—— 获取视图
```
notion-pp-cli views update-a
```
—— 更新视图

sync pages —— 将所有页面和数据库同步到本地SQLite

```
notion-pp-cli sync pages
```
—— 通过搜索API同步所有页面和数据库（执行stale/changed命令前需先运行此命令）
```
notion-pp-cli sync pages --full
```
—— 从头开始完全重新同步

notion-pp-cli sync pages --type database

—— 仅同步数据库

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

means at least one match; exit code

means no confident match — fall back to

--help

or use a narrower query.

当你知道要执行的操作但不确定对应命令时，可直接询问CLI：

bash

notion-pp-cli which "<用自然语言描述所需功能>"

which

命令会将自然语言查询匹配到CLI功能索引中最适合的命令。退出码

表示至少找到一个匹配项；退出码

表示未找到明确匹配项——此时可改用

--help

或缩小查询范围。

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.

bash

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

显示过去8小时内编辑的所有内容——可在会话开始前使用，帮助了解情况后再执行操作。

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.

bash

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

列出30天以上未修改的页面，按修改时间从远到近排序。Notion网页UI无法跨多个工作区实现此筛选功能。

Export a page as markdown

将页面导出为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.

bash

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

通过Notion原生Markdown端点获取页面内容，无需额外转换。

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.

bash

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

列出页面的所有顶级区块及其类型和ID。

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.

需要Notion内部集成令牌。请在notion.so/my-integrations创建令牌，将顶级页面共享给该集成，然后在环境变量中设置

NOTION_BEARER_AUTH

（或

NOTION_TOKEN

）。

首次运行设置：

bash

notion-pp-cli doctor          # 验证认证
notion-pp-cli sync pages      # 同步所有页面和数据库（约15k页面，耗时2-3分钟）
notion-pp-cli stale --days 30 # 现在可正常运行
notion-pp-cli changed --since 24h

执行

notion-pp-cli doctor

验证设置是否正确。

Agent Mode

Agent模式

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

在任何命令后添加

--agent

参数，等效于设置：

--json --compact --no-input --no-color --yes

。

可管道传输 —— 标准输出为JSON，错误信息输出到标准错误
可筛选 ——
```
--select
```
参数保留指定字段。点路径可深入嵌套结构；数组可遍历元素。对于冗长的API，此功能对减少上下文体积至关重要：
bash
```
notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --agent --select id,name,status
```
可预览 ——
```
--dry-run
```
参数显示请求内容但不发送
离线友好 —— 同步/搜索命令可使用本地SQLite存储（若可用）
非交互式 —— 从不弹出提示，所有输入均通过参数传递
显式重试 —— 仅当已存在的创建操作应视为成功时使用
```
--idempotent
```
；仅当缺失的删除目标应视为成功时使用
```
--ignore-missing
```

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.

从本地存储或API读取数据的命令会将输出包装在溯源包中：

json

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

解析

.results

获取数据，通过

.meta.source

判断数据来自实时API还是本地存储。仅当标准输出为终端时，会将人类可读的

N results (live)

摘要输出到标准错误；管道/Agent消费者仅会在标准输出获取纯JSON。

Agent Feedback

Agent反馈

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.

当你（或Agent）发现该CLI存在问题时，可记录反馈：

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

反馈条目会存储在本地

~/.notion-pp-cli/feedback.jsonl

文件中。除非设置了

NOTION_FEEDBACK_ENDPOINT

且传递了

--send

参数或设置

NOTION_FEEDBACK_AUTO_SEND=true

，否则反馈不会被POST发送。默认仅存储在本地。

请记录让你感到意外的内容，而非正式的Bug报告。简短、具体、单条记录：这样的反馈才更有价值。

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:

Sink	Effect
`stdout`	Default; 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.

所有命令均支持

--deliver <sink>

参数。输出会发送到指定目标，同时（或替代）输出到标准输出，以便Agent无需手动管道即可路由命令结果。支持三种目标：

目标	效果
`stdout`	默认值；仅输出到标准输出
`file:<path>`	原子性地将输出写入 `<path>` （先写入临时文件再重命名）
`webhook:<url>`	将输出正文POST到指定URL（ `application/json` 格式，若使用 `--compact` 则为 `application/x-ndjson` 格式）

不支持的协议会返回结构化错误，列出支持的协议类型。Webhook请求失败会返回非零退出码，并在标准错误中记录URL和HTTP状态码。

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.

配置文件是一组保存的参数值，可在多次调用中复用。适用于定时Agent每次运行都调用相同命令并使用相同配置的场景——即HeyGen的“Beacon”模式。

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

显式参数优先级高于配置文件值；配置文件值优先级高于默认值。

agent-context

会在

available_profiles

下列出所有可用配置文件，以便Agent在运行时自动发现。

Exit Codes

退出码

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

代码	含义
0	成功
2	使用错误（参数错误）
3	资源未找到
4	需要认证
5	API错误（上游问题）
7	请求受限（请稍后重试）
10	配置错误

Argument Parsing

参数解析

Parse

$ARGUMENTS

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

解析

$ARGUMENTS

的规则：

为空、
help
或
--help
→ 显示
```
notion-pp-cli --help
```
输出
以
install
开头 → 若结尾为
```
mcp
```
→ 安装MCP；否则 → 参考顶部前提条件中的安装步骤
其他情况 → 直接使用（添加
```
--agent
```
参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP server:

bash

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

bash

claude mcp add notion-pp-mcp -- notion-pp-mcp

Verify:
```
claude mcp list
```

安装MCP服务器：

bash

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

在Claude Code中注册：

bash

claude mcp add notion-pp-mcp -- notion-pp-mcp

验证：
```
claude mcp list
```

Direct Use

直接使用

Check if installed:
```
which notion-pp-cli
```
If not found, offer to install (see Prerequisites at the top of this skill).
Match the user query to the best command from the Unique Capabilities and Command Reference above.

Execute with the

--agent

flag:

bash

notion-pp-cli <command> [subcommand] [args] --agent

If ambiguous, drill into subcommand help:
```
notion-pp-cli <command> --help
```
.

检查是否已安装：
```
which notion-pp-cli
```
若未找到，提供安装选项（参考顶部前提条件）。
将用户查询匹配到“独特功能”和“命令参考”中最合适的命令。

添加

--agent

参数执行命令：

bash

notion-pp-cli <command> [subcommand] [args] --agent

若存在歧义，查看子命令帮助：
```
notion-pp-cli <command> --help
```
。