# @4ier/notion-cli 中文文档

规范地址：https://npmcn.com/package/%404ier/notion-cli/

版本：0\.7\.0
npm 元数据更新时间：2026-04-30T06:16:22.028Z
中文译文更新时间：2026-11-08T09:53:15.939Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%404ier/notion-cli
原文对照：https://npmcn.com/package/%404ier/notion-cli/?lang=original
项目主页：https://github.com/4ier/notion-cli
源码仓库：https://github.com/4ier/notion-cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：12.7 kB，6 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=16
- 运行依赖：0 个
- 首次发布：2026-02-24T06:36:30.389Z
- 最新版本发布：2026-04-30T06:16:21.923Z
- 近 30 天下载量：1818（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

全能CLI用于Notion. 就像GitHub的Gh,但是对于Notion的。 44个命令,一个二进制.

## 安装

```sh
npm install @4ier/notion-cli
```

也可以使用：`pnpm add @4ier/notion-cli`、`yarn add @4ier/notion-cli`、`bun add @4ier/notion-cli`

## README

# 概念 - cli

**喜欢 `gh` 给GitHub 但给Notion 39命令 一个二进制.**

![demo](https://github.com/4ier/notion-cli/releases/download/v0.2.0/demo.gif)

[![Release](https://img.shields.io/github/v/release/4ier/notion-cli?style=flat-square)](https://github.com/4ier/notion-cli/releases) [![Tests](https://img.shields.io/github/actions/workflow/status/4ier/notion-cli/test.yml?style=flat-square&label=tests)](https://github.com/4ier/notion-cli/actions) [![License](https://img.shields.io/github/license/4ier/notion-cli?style=flat-square)](https://github.com/4ier/notion-cli/blob/main/LICENSE) [![Go Report Card](https://goreportcard.com/badge/github.com/4ier/notion-cli?style=flat-square)](https://goreportcard.com/report/github.com/4ier/notion-cli)

* * *

完整的命令行接口 [标题](https://notion.so/)。管理页面、数据库、块、评论、用户和文件——都来自您的终端。 为需要程序访问而无需浏览器的开发者和AI代理所建.

## 安装

### 家庭工作人员(MacOS/Linux)

```sh
brew install 4ier/tap/notion-cli
```

### 走开

```sh
go install github.com/4ier/notion-cli@latest
```

### 无

```sh
npm install -g @4ier/notion-cli
```

### Scoop (窗户)

```powershell
scoop bucket add 4ier https://github.com/4ier/scoop-bucket
scoop install notion-cli
```

### 夹克

```sh
docker run --rm -e NOTION_TOKEN ghcr.io/4ier/notion-cli search "meeting"
```

### 二进制

从 [GitHub 发布](https://github.com/4ier/notion-cli/releases) ——可供Linux,macOS,和Windows(amd64/arm64)使用.

## 快速启动

```sh
# Authenticate
echo "ntn_xxxxx" | notion auth login --with-token

# Search your workspace
notion search "meeting notes"

# Query a database with filters
notion db query <db-id> --filter 'Status=Done' --sort 'Date:desc'

# Create a page in a database
notion page create <db-id> --db "Name=Weekly Review" "Status=Todo"

# Read page content as Markdown
notion block list <page-id> --depth 3 --md

# Append blocks from a Markdown file
notion block append <page-id> --file notes.md

# Raw API escape hatch
notion api GET /v1/users/me
```

## 图标

| 组 | 图标 | 说明 |
| --- | --- | --- |
| **认证** | `login` `logout` `status` `switch` `doctor` | 认证和诊断 |
| **搜索** | `search` | 搜索页面和数据库 |
| **页 次** | `view` `list` `create` `delete` `restore` `move` `open` `set` `props` `link` `unlink` | 全页寿命周期 |
| **页:1** | `list` `view` `query` `create` `update` `add` `add-bulk` `open` | 数据库 CRUD + 查询 |
| **块** | `list` `get` `append` `insert` `update` `delete` | 内容块操作 |
| **注释** | `list` `add` `get` | 讨论线索 |
| **用户** | `me` `list` `get` | 工作空间成员 |
| **文件** | `list` `upload` | 文件管理 |
| **api 密码** | `<METHOD> <path>` | 原始 API 逃生舱口 |

**39个子命令** 覆盖 API 的100%.

## 特征

### 爱人过滤器

90%的询问不需要 JSON :

```sh
notion db query <id> --filter 'Status=Done' --filter 'Priority=High' --sort 'Date:desc'
```

对于复杂的查询(OR,筑巢),使用JSON出逃舱口:

```sh
notion db query <id> --filter-json '{"or":[{"property":"Status","status":{"equals":"Done"}},{"property":"Status","status":{"equals":"Cancelled"}}]}'
```

### Schema- Aware 属性

属性类型从数据库中自动检测:

```sh
notion page create <db-id> --db "Name=Sprint Review" "Date=2026-03-01" "Points=8" "Done=true"
```

### 智能输出

-   **终端**: 有色表格,格式化文本
-   **管道/脚本**清洁JSON为 `jq`、脚本和AI代理商

```sh
# Pretty table in terminal
notion db query <id>

# JSON when piped
notion db query <id> | jq '.results[].properties.Name'
```

### 标记一/O

```sh
# Read blocks as Markdown
notion block list <page-id> --md --depth 3

# Write Markdown to Notion
notion block append <page-id> --file document.md
```

支持标题、项目符号、列表、待办事宜、引用、代码块和分隔符.

### 外部图像

通过 URL 插入或附加一个图像块( 不上传- 指向外部主机图像) :

```sh
# Insert after a specific block (e.g. next to a "TODO: add figure" placeholder)
notion block insert <page-id> --after <block-id> \
  --image-url https://example.com/diagram.png \
  --caption "Figure 1 — architecture"

# Append to end of page
notion block append <page-id> --image-url https://example.com/diagram.png
```

### 递归屏蔽读取

```sh
notion block list <page-id> --depth 5 --all
```

### URL 或 ID - 您的选择

```sh
# Both work
notion page view abc123def
notion page view https://notion.so/My-Page-abc123def456
```

### 可操作错误消息

```
object_not_found: Could not find page with ID abc123
  → Check the ID is correct and the page/database is shared with your integration
```

## 为大赦国际代理

设计这种CLI是为了方便代理:

-   **JSON 输出** 管道时——不需要解析
-   **斯克玛 - 认识** - 特工不需要知道财产类型
-   **URL 分辨率** ——直接粘贴逗号 URL
-   **单二进制** 无运行时间依赖关系
-   **退出代码** 成功0分,出错0分

安装为代理技能 :

```sh
npx skills add 4ier/notion-cli
```

## 配置

```sh
# Token is stored in ~/.config/notion-cli/config.json (mode 0600)
echo "ntn_xxxxx" | notion auth login --with-token

# Or use environment variable
export NOTION_TOKEN=ntn_xxxxx

# Check authentication
notion auth status
notion auth doctor
```

## 解决问题

### 窗口: MSYS / Git Bash 路径管理

在基于 MSYS (Git Bash, MSYS2) 中, 参数以 `/` 静默地重写到 Windows 路径。 中断 API 路径参数 :

```sh
# ✗ /v1/users/me becomes C:/Program Files/Git/v1/users/me
notion api GET /v1/users/me
```

**修补 :** 禁用 MSYS 路径转换 :

```sh
MSYS_NO_PATHCONV=1 notion api GET /v1/users/me
```

或导出为会话 : `export MSYS_NO_PATHCONV=1`

> 这是一个贝壳级的问题,不是概念-cli中的bug. PowerShell和cmd.exe没有受到影响.

## 捐款

问题和企业责任 [github.com/4ier/notion-cli (中文(简体) )](https://github.com/4ier/notion-cli)。 。 。 .

## 许可证

[麻省理工学院](https://npmcn.com/package/%404ier/notion-cli/LICENSE)

## 常见问题

### @4ier/notion-cli 是什么？

全能CLI用于Notion\. 就像GitHub的Gh,但是对于Notion的。 44个命令,一个二进制\.

### 如何安装 @4ier/notion-cli？

在项目目录运行 npm install @4ier/notion-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 notion，可以用 npx notion 直接运行。

### @4ier/notion-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/4ier\_\_notion-cli 是否存在。

### @4ier/notion-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @4ier/notion-cli 可以商用吗？

@4ier/notion-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @4ier/notion-cli 的下载量有多少？

根据 npm 官方下载统计，@4ier/notion-cli 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,818 次，日均约 61 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @4ier/notion-cli 还在维护吗？

最新版本 0\.7\.0 发布于 2026/04/30（6 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/02/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。