ntion CLI

Notion CLI. Run via

npx ntion

(or

ntion

if installed globally).

Notion命令行工具。可通过

npx ntion

运行（若全局安装则直接使用

ntion

）。

Authentication

认证

Authentication is a one-time setup stored in

~/.config/ntion/config.json

. If a command fails with exit code 6 (auth error), prompt the user to run

ntion auth

.

bash

ntion auth --token "secret_xxx"

认证设置为一次性操作，配置信息将存储在

~/.config/ntion/config.json

中。若命令因退出码6（认证错误）失败，请提示用户运行

ntion auth

。

bash

ntion auth --token "secret_xxx"

Or interactive: ntion auth

Verify: ntion doctor


Token is created at https://www.notion.so/profile/integrations.


Token可在https://www.notion.so/profile/integrations创建。

Commands

命令

search

bash

ntion search --query "meeting notes"
ntion search --query "tasks" --object page --limit 10
ntion search --query "Q1" --created-after 2026-01-01T00:00:00Z

Options:

--query

(required),

--scope <id>

,

--object page|data_source

,

--created-after/--created-before

,

--edited-after/--edited-before

,

--created-by <user_id>

,

--limit

,

--cursor

,

--scan-limit

,

--view compact|full

,

--pretty

.

bash

ntion search --query "meeting notes"
ntion search --query "tasks" --object page --limit 10
ntion search --query "Q1" --created-after 2026-01-01T00:00:00Z

选项：

--query

（必填）、

--scope <id>

、

--object page|data_source

、

--created-after/--created-before

、

--edited-after/--edited-before

、

--created-by <user_id>

、

--limit

、

--cursor

、

--scan-limit

、

--view compact|full

、

--pretty

。

data-sources (databases)

数据源（数据库）

bash

ntion data-sources list --query "tasks"
ntion data-sources get --id <id> --view full
ntion data-sources schema --id <id>
ntion data-sources query --id <id> \
  --filter-json '{"property":"Status","status":{"equals":"In Progress"}}' \
  --sort-json '{"property":"Created","direction":"descending"}' \
  --limit 50

Use

schema

to discover property names and types before querying or creating pages. Filter/sort JSON follows the Notion API filter format.

bash

ntion data-sources list --query "tasks"
ntion data-sources get --id <id> --view full
ntion data-sources schema --id <id>
ntion data-sources query --id <id> \
  --filter-json '{"property":"Status","status":{"equals":"In Progress"}}' \
  --sort-json '{"property":"Created","direction":"descending"}' \
  --limit 50

使用

schema

命令可在查询或创建页面之前了解属性名称和类型。过滤/排序JSON需遵循Notion API的过滤格式。

pages

页面

bash

undefined

bash

undefined

Read

读取

ntion pages get --id <id> ntion pages get --id <id> --include-content --content-format markdown

Create

创建

ntion pages create
--parent-data-source-id <ds_id>
--properties-json '{"Name":"New task","Status":"Not started"}'

Bulk create (up to 100)

批量创建（最多100个）

ntion pages create-bulk
--parent-data-source-id <ds_id>
--items-json '[{"properties":{"Name":"A"}},{"properties":{"Name":"B"}}]'

Update

更新

ntion pages update --id <id> --patch-json '{"Status":"Done"}'

Archive / restore

归档 / 恢复

ntion pages archive --id <id> ntion pages unarchive --id <id>

Relations

关联

ntion pages relate --from-id <id> --property "Project" --to-id <target_id> ntion pages unrelate --from-id <id> --property "Project" --to-id <target_id>

undefined

ntion pages relate --from-id <id> --property "Project" --to-id <target_id> ntion pages unrelate --from-id <id> --property "Project" --to-id <target_id>

undefined

blocks (page content)

块（页面内容）

bash

undefined

bash

undefined

Read content as markdown

以Markdown格式读取内容

ntion blocks get --id <page_or_block_id> ntion blocks get --id <id> --depth 2 --format compact

Append to end

追加至末尾

ntion blocks append --id <id> --markdown $'## Section\n\nContent here' ntion blocks append --id <id> --markdown-file ./notes.md

Insert at position

插入到指定位置

ntion blocks insert --parent-id <id> --markdown "Intro text" --position start ntion blocks insert --parent-id <id> --markdown "Middle" --after-id <block_id>

Find blocks

查找块

ntion blocks select
--scope-id <id>
--selector-json '{"where":{"type":"paragraph","text_contains":"TODO"}}'

Replace block range

替换块范围

ntion blocks replace-range
--scope-id <id>
--start-selector-json '{"where":{"text_contains":"## Old Section"}}'
--end-selector-json '{"where":{"text_contains":"## Next Section"}}'
--markdown "## New Section\n\nUpdated content"

Delete blocks

删除块

ntion blocks delete --ids <block_id> ntion blocks delete --ids <id1> <id2> <id3>

undefined

ntion blocks delete --ids <block_id> ntion blocks delete --ids <id1> <id2> <id3>

undefined

Workflow patterns

工作流模式

Discover → Query → Act

发现 → 查询 → 操作

Find the database:
```
ntion data-sources list --query "tasks"
```
Get its schema:
```
ntion data-sources schema --id <id>
```

Query with filters:

ntion data-sources query --id <id> --filter-json '...'

Create/update pages using the discovered property names

查找数据库：
```
ntion data-sources list --query "tasks"
```
获取其结构：
```
ntion data-sources schema --id <id>
```

带过滤条件查询：

ntion data-sources query --id <id> --filter-json '...'

使用已获取的属性名称创建/更新页面

Read → Edit page content

读取 → 编辑页面内容

Read current content:
```
ntion blocks get --id <page_id>
```

Append new content:

ntion blocks append --id <page_id> --markdown "..."

Or replace a section: use
```
blocks replace-range
```
with selectors
Delete specific blocks:
```
ntion blocks delete --ids <id1> <id2>
```

读取当前内容：
```
ntion blocks get --id <page_id>
```

追加新内容：

ntion blocks append --id <page_id> --markdown "..."

或替换某个章节：使用
```
blocks replace-range
```
命令配合选择器
删除特定块：
```
ntion blocks delete --ids <id1> <id2>
```

Output format

输出格式

All commands return JSON envelopes:

json

{"ok": true, "data": {...}, "meta": {"request_id": "..."}}
{"ok": false, "error": {"code": "not_found", "message": "...", "retryable": false}, "meta": {...}}

Exit codes: 0=success, 1=failure, 2=invalid input, 3=not found, 4=conflict, 5=retryable, 6=auth error.

所有命令均返回JSON格式结果：

json

{"ok": true, "data": {...}, "meta": {"request_id": "..."}}
{"ok": false, "error": {"code": "not_found", "message": "...", "retryable": false}, "meta": {...}}

退出码：0=成功，1=失败，2=输入无效，3=未找到，4=冲突，5=可重试，6=认证错误。

Notes

注意事项

```
--view compact
```
(default) returns minimal data. Use
```
--view full
```
when complete details are needed.
Mutations are idempotent with verify-first recovery on ambiguous outcomes. Re-read before retrying when the CLI reports uncertainty.
Bulk create supports
```
--concurrency
```
(default 5) for parallel operations.
Use
```
--pretty
```
on any command for human-readable JSON output.

```
--view compact
```
（默认）返回精简数据。当需要完整详情时，请使用
```
--view full
```
。
变更操作具有幂等性，在结果不明确时会先验证再恢复。当CLI报告不确定结果时，请重新读取后再重试。
批量创建支持
```
--concurrency
```
参数（默认值为5）以实现并行操作。
任何命令都可添加
```
--pretty
```
参数以获得人类可读的JSON输出。

ntion-cli

Original

Translation

ntion CLI

ntion CLI

Authentication

认证

Or interactive: ntion auth

Or interactive: ntion auth

Verify: ntion doctor

Verify: ntion doctor

Commands

命令

search

search

data-sources (databases)

数据源（数据库）

pages

页面

Read

读取

Create

创建

Bulk create (up to 100)

批量创建（最多100个）

Update

更新

Archive / restore

归档 / 恢复

Relations

关联

blocks (page content)

块（页面内容）

Read content as markdown

以Markdown格式读取内容

Append to end

追加至末尾

Insert at position

插入到指定位置

Find blocks

查找块

Replace block range

替换块范围

Delete blocks

删除块

Workflow patterns

工作流模式

Discover → Query → Act

发现 → 查询 → 操作

Read → Edit page content

读取 → 编辑页面内容

Output format

输出格式

Notes

注意事项