notion-cli

A command-line interface for Notion using the remote MCP (Model Context Protocol).

Inspired by linear-cli - stay in the terminal while managing your Notion workspace.

Works great with AI agents — includes a skill that lets agents search, create, and manage your Notion workspace alongside your code.

Installation

From Source

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

Build Locally

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

Quick Start

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

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

# View a page
notion-cli page view "https://notion.so/My-Page-abc123"

# List your pages
notion-cli page list

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

Commands

Authentication

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

Pages

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 <url>                     # View page content
notion-cli page view <url> --raw               # View raw Notion markup
notion-cli page view <url> --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>

# 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

# 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

# Edit an existing page
notion-cli page edit <url> --replace "New content"                      # Replace all content
notion-cli page edit <url> --find "old text" --replace-with "new text"  # Find and replace
notion-cli page edit <url> --find "section" --append "extra content"    # Append after match

Search

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

Databases

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

The <database> argument accepts a URL, ID, or name. Date properties use the expanded key format: date:<Property Name>:start, date:<Property Name>:end.

Comments

notion-cli comment list <page-id>              # List comments on a page
notion-cli comment list <page-id> --json       # Output as JSON

notion-cli comment create <page-id> --content "Comment text"

Other

notion-cli version                             # Show version
notion-cli --help                              # Show help

Configuration

Configuration is stored at ~/.config/notion-cli/config.json.

The CLI uses Notion's remote MCP server with OAuth authentication. On first run, notion-cli auth login will open your browser to authorize the CLI with your Notion workspace.

Note: Access tokens expire after 1 hour. The CLI automatically refreshes tokens when they expire or are about to expire, so you typically don't need to think about this. Use notion-cli auth refresh to manually refresh if needed.

Environment Variables

Variable	Description
`NOTION_ACCESS_TOKEN`	Access token for CI/headless usage (skips OAuth)

How It Works

This CLI connects to Notion's remote MCP server at https://mcp.notion.com/mcp using the Model Context Protocol. This provides:

OAuth authentication - No API tokens to manage
Notion-flavoured Markdown - Create/edit content naturally
Semantic search - Search across connected apps too
Optimised for CLI - Efficient responses

Skills

notion-cli includes a skill that helps AI agents use the CLI effectively.

Amp / Claude Code

Install the skill using skills.sh:

npx skills add lox/notion-cli

Or manually add to your Amp/Claude config:

# 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

View the skill at: skills/notion/SKILL.md

License

MIT License - see LICENSE for details.

mipearson/notion-cli

README