notion-cli
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.
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).
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.