AI导哈

Notion命令行工具

一个通过远程MCP协议管理Notion工作空间的命令行工具，支持页面/数据库操作、搜索及AI代理集成

  • by lox
  • Go
  • 本地部署
  • 36 星标
  • 更新于
在 GitHub 查看 lox/notion-cli

使用说明

概念cli

Notion使用远程MCP（模型上下文协议）的命令行界面。

受到启发 线性气候 -在管理Notion工作区时，请留在终端中。

与AI代理配合得很好 --包括a 技能 它允许代理在代码旁边搜索、创建和管理您的Notion工作区。

安装

来源

go install github.com/lox/notion-cli@latest

本地建设

git clone https://github.com/lox/notion-cli
cd notion-cli
mise run build

快速开始

# Authenticate with Notion (opens browser for OAuth)
notion-cli auth login

# Search your workspace
notion-cli search "meeting notes"

# View a page with open comments inline by default
notion-cli page view "https://notion.so/My-Page-abc123"

# Hide page and block comments when you only want the body
notion-cli page view "Meeting Notes" --no-comments

# List your pages
notion-cli page list

# Create a page
notion-cli page create --title "New Page" --content "# Hello World"

命令

认证

notion-cli auth login      # Authenticate with Notion via OAuth
notion-cli auth refresh    # Refresh the access token
notion-cli auth status     # Show authentication status
notion-cli auth logout     # Clear stored credentials

# Official API fallback auth for features MCP cannot handle directly
notion-cli auth api setup     # Opens the internal integrations page, prompts for token, warns if format looks wrong
notion-cli auth api status
notion-cli auth api verify
notion-cli auth api unset

页面

notion-cli page list                           # List pages
notion-cli page list --limit 50                # Limit results
notion-cli page list --json                    # Output as JSON

notion-cli page view <page>                    # View page content with comments
notion-cli page view <page> --no-comments      # Hide page and block comments
notion-cli page view <page> --raw              # View raw Notion markup
notion-cli page view <page> --json             # Output as JSON

notion-cli page create --title "Title"         # Create a page
notion-cli page create --title "T" --content "Body text"
notion-cli page create --title "T" --parent <page-id>
notion-cli page archive <page-url-or-id>       # Archive a page via the official API

# Upload a markdown file as a new page
notion-cli page upload ./document.md                        # Title from # heading or filename
notion-cli page upload ./document.md --title "Custom Title" # Explicit title
notion-cli page upload ./document.md --parent "Engineering" # Parent by name or ID
notion-cli page upload ./document.md --parent-db <db-id>    # Upload as database entry
notion-cli page upload ./document.md --icon "📄"             # Set emoji icon
notion-cli page upload ./document.md                        # Uploads standalone local images when configured
notion-cli page upload ./document.md --skip-local-images    # Strips standalone local image lines instead

# Sync a markdown file (create or update)
notion-cli page sync ./document.md                          # Creates page, writes notion-id to frontmatter
notion-cli page sync ./document.md                          # Updates page using notion-id from frontmatter
notion-cli page sync ./document.md --parent "Engineering"   # Set parent on first sync
notion-cli page sync ./document.md --parent-db <db-id>      # Sync as database entry
notion-cli page sync ./document.md                          # Uploads standalone local images when configured
notion-cli page sync ./document.md --skip-local-images      # Strips standalone local image lines instead

# Edit an existing page
notion-cli page edit <page> --replace "New content"                      # Replace all content
notion-cli page edit <page> --replace "New content" --allow-deleting-content # Allow replacing pages with child content
notion-cli page edit <page> --find "old text" --replace-with "new text"  # Find and replace
notion-cli page edit <page> --find "section" --append "extra content"    # Append after match
notion-cli page edit <page> -P "Status=Done" -P "Priority=1"             # Update page properties

这 <page> 参数接受URL、ID或页面名称。

page archive 接受页面URL或页面ID，并通过官方API将该页面移到垃圾桶中。这需要通过配置官方API令牌 auth api setup 或 NOTION_API_TOKEN.

page view 默认情况下，显示打开页面级别的评论和内联块讨论。内联讨论在上下文中呈现，锚文本包裹在 [[...]] 下面显示的讨论。使用 --no-comments 为了抑制评论， --raw 检查原始Notion标记，以及 --json 返回页面加上a Comments 阵列。

page upload 和 page sync 支持本地图像上传，用于独立的markdown图像行，如 ![Alt](./diagram.png)当存在局部图像时， notion-cli 通过官方的Notion API上传这些文件，并按文档顺序保存。这需要通过配置官方API令牌 auth api setup 或 NOTION_API_TOKEN.通行证 --skip-local-images 默默地删除独立的本地图像行，而不是上传它们。内联或混合内容本地图像语法被拒绝，而不是被猜测。

搜索

notion-cli search "query"                      # Search workspace
notion-cli search "query" --limit 10           # Limit results
notion-cli search "query" --json               # Output as JSON

数据库

notion-cli db list                             # List databases
notion-cli db list -q "project"                # Filter by name
notion-cli db list --json                      # Output as JSON

notion-cli db query <database-id>              # Query database
notion-cli db query <id> --json                # Output as JSON

# Create an entry in a database
notion-cli db create <database> --title "Entry Title"
notion-cli db create <database> -t "Title" --prop "Status=Not started"
notion-cli db create <database> -t "Title" --prop "Status=Done" --prop "date:Due:start=2026-03-01"
notion-cli db create <database> -t "Title" --content "Body text"
notion-cli db create <database> -t "Title" --file ./notes.md
notion-cli db create <database> -t "Title" --json

这 <database> 参数接受URL、ID或名称。日期属性使用扩展密钥格式： date:<Property Name>:start, date:<Property Name>:end.

评论

notion-cli comment list <page>                 # List open page and block comments
notion-cli comment list <page> --resolved      # Include resolved discussions too
notion-cli comment list <page> --json          # Output as JSON
notion-cli comment list "Meeting Notes"        # Resolve the page by name

notion-cli comment create <page> --content "Comment text"
notion-cli comment create https://notion.so/... --content "Looks good"

注释命令接受页面URL、ID或名称。 comment list 默认情况下，包括页面级和块级讨论，除非您通过，否则仅显示打开的讨论 --resolved.

其他

notion-cli tools                               # List available MCP tools
notion-cli tools --json                        # Output tools as JSON
notion-cli version                             # Show version
notion-cli --version                           # Alias for version
notion-cli -v                                  # Short alias for version
notion-cli --help                              # Show help

配置

CLI使用Notion的远程MCP服务器进行OAuth身份验证。在第一次运行时， notion-cli auth login 将打开浏览器，通过Notion工作区授权CLI。

注： 访问令牌将在1小时后过期。当令牌过期或即将过期时，CLI会自动刷新令牌，因此您通常不需要考虑这一点。使用 notion-cli auth refresh 如果需要，可以手动刷新。

档案

每个命令都接受 --profile <name> （或 NOTION_CLI_PROFILE)将OAuth令牌和官方API配置范围定为特定的Notion帐户，因此您可以分别登录 work, home等等。

# Log in to a named profile
notion-cli auth login --profile work

# Use the profile for a single command
notion-cli page list --profile work

# Pin a profile for the shell session
export NOTION_CLI_PROFILE=work

# Make a profile the default for future invocations
notion-cli auth use work

配置文件分辨率，最高优先级优先：

  1. --profile <name> 旗帜
  2. NOTION_CLI_PROFILE 环境变量
  3. 活动配置文件来自 notion-cli auth use <name>
  4. 隐式默认配置文件

默认配置文件继续使用现有的OAuth令牌路径，因此现有的单帐户安装不需要迁移。 notion-cli auth use <name> 将活动配置文件存储在cross-profile配置目录中。

配置文件名称必须以小写ASCII字母或数字开头和结尾。它们可能包含小写字母、数字、at符号、点、下划线和连字符。

命名配置文件将其凭据存储在 ~/.config/notion-cli/profiles/<profile>/{token,config}.json.

notion-cli auth status 打印所选的配置文件和令牌路径，以及 notion-cli auth list 显示了具有OAuth和API到ken状态的所有已知配置文件。

环境变量

变量 描述
NOTION_ACCESS_TOKEN 用于CI/无头使用的访问令牌（跳过OAuth）
NOTION_API_TOKEN 用于上传回退和验证的官方Notion API令牌
NOTION_API_BASE_URL 覆盖官方的Notion API基础URL
NOTION_API_NOTION_VERSION 覆盖官方Notion API版本
NOTION_CLI_PROFILE 默认配置文件 --profile 未通过

运作原理

此CLI连接到 Notion的远程MCP服务器 在 https://mcp.notion.com/mcp 使用模型上下文协议。这提供了：

  • OAuth身份验证 -没有要管理的API令牌
  • Notion风格的Markdown -自然地创建/编辑内容
  • 语义搜索 -也可以在连接的应用程序中搜索
  • 针对CLI进行了优化 -高效响应

技能

cli概念包括一种帮助AI代理有效使用cli的技能。

安培/克劳德码

使用安装技能 技能s.sh:

npx skills add lox/notion-cli

或者手动添加到Amp/Claude配置中：

# Amp
amp skill add https://github.com/lox/notion-cli/tree/main/skills/notion-cli

# Claude Code
claude plugin marketplace add lox/notion-cli
claude plugin install notion-cli@notion-cli

在以下网址查看技能： 技能/概念/SKILL.md

链接

许可证

MIT许可证-请参阅 许可证 了解详情。

相关 MCP