Like gh for GitHub, but for Notion. 39 commands. One binary.
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.
brew install 4ier/tap/notion-cligo install github.com/4ier/notion-cli@latestnpm install -g @4ier/notion-cliscoop bucket add 4ier https://github.com/4ier/scoop-bucket
scoop install notion-clidocker run --rm -e NOTION_TOKEN ghcr.io/4ier/notion-cli search "meeting"Download from GitHub Releases — available for Linux, macOS, and Windows (amd64/arm64).
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.
# 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| 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.
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"}}]}'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"- 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'# Read blocks as Markdown
notion block list <page-id> --md --depth 3
# Write Markdown to Notion
notion block append <page-id> --file document.mdSupports headings, bullets, numbered lists, todos, quotes, code blocks, and dividers.
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.pngnotion block list <page-id> --depth 5 --all# Both work
notion page view abc123def
notion page view https://notion.so/My-Page-abc123def456object_not_found: Could not find page with ID abc123
→ Check the ID is correct and the page/database is shared with your integration
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# 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 doctorIn 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/meFix: disable MSYS path conversion:
MSYS_NO_PATHCONV=1 notion api GET /v1/users/meOr 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.
Issues and PRs welcome at github.com/4ier/notion-cli.