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 with open comments inline by default
notion-cli page view "https://notion.so/My-Page-abc123"

# Hide page and block comments when you only want the body
notion-cli page view "Meeting Notes" --no-comments

# 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

# Official API fallback auth for features MCP cannot handle directly
notion-cli auth api setup     # Opens the internal integrations page, then prompts for token
notion-cli auth api status
notion-cli auth api verify
notion-cli auth api unset

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 <page>                    # View page content with comments
notion-cli page view <page> --no-comments      # Hide page and block comments
notion-cli page view <page> --raw              # View raw Notion markup
notion-cli page view <page> --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
notion-cli page upload ./document.md                        # Uploads standalone local images when configured

# 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
notion-cli page sync ./document.md                          # Uploads standalone local images when configured

# Edit an existing page
notion-cli page edit <page> --replace "New content"                      # Replace all content
notion-cli page edit <page> --replace "New content" --allow-deleting-content # Allow replacing pages with child content
notion-cli page edit <page> --find "old text" --replace-with "new text"  # Find and replace
notion-cli page edit <page> --find "section" --append "extra content"    # Append after match
notion-cli page edit <page> -P "Status=Done" -P "Priority=1"             # Update page properties

The <page> argument accepts a URL, ID, or page name.

page view shows open page-level comments and inline block discussions by default. Inline discussions are rendered in context, with the anchor text wrapped in [[...]] and the discussion shown immediately below it. Use --no-comments to suppress comments, --raw to inspect the original Notion markup, and --json to return the page plus a Comments array.

page upload and page sync support native local image upload for standalone markdown image lines like ![Alt](./diagram.png). When local images are present, notion-cli uploads those files through the official Notion API and keeps them in document order. This requires an official API token configured through auth api setup or NOTION_API_TOKEN. Inline or mixed-content local image syntax is rejected instead of being guessed.

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>                 # List open page and block comments
notion-cli comment list <page> --resolved      # Include resolved discussions too
notion-cli comment list <page> --json          # Output as JSON
notion-cli comment list "Meeting Notes"        # Resolve the page by name

notion-cli comment create <page> --content "Comment text"
notion-cli comment create https://notion.so/... --content "Looks good"

The comment commands accept a page URL, ID, or name. comment list includes both page-level and block-level discussions by default and only shows open discussions unless you pass --resolved.

Other

notion-cli tools                               # List available MCP tools
notion-cli tools --json                        # Output tools as JSON
notion-cli version                             # Show version
notion-cli --version                           # Alias for version
notion-cli -v                                  # Short alias for 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)
NOTION_API_TOKEN	Official Notion API token used for upload fallback and verification
NOTION_API_BASE_URL	Override the official Notion API base URL
NOTION_API_NOTION_VERSION	Override the official Notion API version

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

Links

• Notion MCP Documentation
• Notion API Reference
• Model Context Protocol

License

MIT License - see LICENSE for details.