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 notion-cli-go

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
notion auth login --token ntn_xxxxx

# 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

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.

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)
notion auth login --token ntn_xxxxx

# Or use environment variable
export NOTION_TOKEN=ntn_xxxxx

# Check authentication
notion auth status
notion auth doctor

Contributing

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

License

MIT