notion-cli

---

A full-featured command-line interface for Notion. Manage pages, databases, blocks, comments, users, and files — all from your terminal. Built for developers and AI agents who need programmatic access without the browser.

Install

Homebrew (macOS/Linux)

brew install 4ier/tap/notion-cli

Go

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

npm

npm install -g @4ier/notion-cli

Scoop (Windows)

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

Docker

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

Binary

Download from GitHub Releases — available for Linux, macOS, and Windows (amd64/arm64).

How does this compare to Notion's official ntn CLI?

Notion launched an official CLI named ntn in 2026. They're both real, both useful, and they overlap less than the names suggest.

	notion-cli (this)	ntn (official)
Maintainer	Open source, MIT, fully on GitHub	Notion (core binary not open source)
Status	Stable releases since v0.1.0	Public Beta
Auth	Internal integration token (NOTION_TOKEN or auth login --with-token)	Browser OAuth login + keychain, or NOTION_API_TOKEN
Platforms	Linux, macOS, Windows	Linux, macOS (Windows not supported)
API surface	Full CRUD across pages, databases, blocks, comments, users, search, files	Pages (Markdown round-trip), data source query, files, raw api
Workers / runtime	Out of scope	First-class (ntn workers new/deploy)
Design intent	Ergonomic resource access for humans, scripts, and AI agents	Build and deploy Notion Workers, plus convenience access to a few resources

Pick ntn if you want OAuth login, you're building Notion Workers, or you prefer a first-party tool on macOS/Linux.

Pick notion-cli if you need broad resource CRUD (blocks, comments, users, search, full database CRUD), you're on Windows, you prefer a fully open-source binary, or you're driving Notion from scripts and AI agents using a long-lived integration token.

The two tools coexist on the same machine without conflict — ntn calls itself ntn, this one calls itself notion.

Quick Start

# 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

Commands

Group	Commands	Description
auth	login logout status switch doctor	Authentication & diagnostics
search	search	Search pages and databases
page	view list create delete restore move open set props link unlink	Full page lifecycle
db	list view query create update add add-bulk open	Database CRUD + query
block	list get append insert update delete	Content block operations
comment	list add get	Discussion threads
user	me list get	Workspace members
file	list upload	File management
api	<METHOD> <path>	Raw API escape hatch

39 subcommands covering 100% of the Notion API.

Features

Human-Friendly Filters

No JSON needed for 90% of queries:

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

For complex queries (OR, nesting), use the JSON escape hatch:

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

Schema-Aware Properties

Property types are auto-detected from the database schema:

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

Smart Output

• Terminal: Colored tables, formatted text
• Pipe/Script: Clean JSON for jq, scripts, and AI agents

# Pretty table in terminal
notion db query <id>

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

Markdown I/O

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

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

Supports headings, bullets, numbered lists, todos, quotes, code blocks, and dividers.

External Images

Insert or append an image block by URL (no upload — points to externally hosted image):

# 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

Recursive Block Reading

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

URL or ID — Your Choice

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

Actionable Error Messages

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

For AI Agents

This CLI is designed to be agent-friendly:

• JSON output when piped — no parsing needed
• Schema-aware — agents don't need to know property types
• URL resolution — paste Notion URLs directly
• Single binary — no runtime dependencies
• Exit codes — 0 for success, non-zero for errors

Install as an agent skill:

npx skills add 4ier/notion-cli

Configuration

# 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

Troubleshooting

Windows: MSYS / Git Bash path mangling

In MSYS-based shells (Git Bash, MSYS2), arguments starting with / are silently rewritten to Windows paths. This breaks API path arguments:

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

Fix: disable MSYS path conversion:

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

Or export it for the session: export MSYS_NO_PATHCONV=1

This is a shell-level issue, not a bug in notion-cli. PowerShell and cmd.exe are not affected.

Contributing

Issues and PRs welcome at github.com/4ier/notion-cli.

License

MIT