notion-cli

README

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.

This is a fork of lox/notion-cli that adds a generic tools call command for invoking any Notion MCP tool by name (e.g. notion-query-data-sources), plus --json input schemas in tools list. Everything else is upstream.

Installation

As a dependency (install the pinned binary)

Install the CLI straight from this repository — this is the recommended way to depend on it from another project's tooling, scripts, or CI:

# latest from the default branch
go install github.com/miguelpalomera/notion-cli@latest

# or pin an exact tag / commit for reproducible builds (recommended for CI)
go install github.com/miguelpalomera/notion-cli@v0.1.0
go install github.com/miguelpalomera/notion-cli@<commit-sha>

This drops a notion-cli binary in $(go env GOPATH)/bin (put that on your PATH). Requires Go 1.22+. In CI, run the same go install …@<tag> step before invoking notion-cli.

Build Locally

git clone https://github.com/miguelpalomera/notion-cli
cd notion-cli
mise run build     # or: go build -o notion-cli .

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, prompts for token, warns if format looks wrong
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>
notion-cli page archive <page-url-or-id>       # Archive a page via the official API

# 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
notion-cli page upload ./document.md --skip-local-images    # Strips standalone local image lines instead

# 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
notion-cli page sync ./document.md --skip-local-images      # Strips standalone local image lines instead

# 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 archive accepts a page URL or page ID and moves that page to trash via the official API. This requires an official API token configured through auth api setup or NOTION_API_TOKEN.

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. Pass --skip-local-images to silently remove standalone local image lines instead of uploading them. 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 (includes each tool's inputSchema)
notion-cli version                             # Show version
notion-cli --version                           # Alias for version
notion-cli -v                                  # Short alias for version
notion-cli --help                              # Show help

Calling any MCP tool

tools call is a generic escape hatch: it invokes any Notion MCP tool by name with a JSON argument object, so you can reach capabilities that have no dedicated subcommand (for example querying a data source's rows). Discover tool names and their argument schemas with notion-cli tools --json.

# arguments inline as a JSON object
notion-cli tools call notion-fetch --args '{"id":"<page-or-db-id>"}'

# arguments from a file, or from stdin with "-"
notion-cli tools call notion-query-data-sources --args-file ./query.json
echo '{"data":{"mode":"sql","data_source_urls":["collection://<id>"],"query":"SELECT * FROM \"collection://<id>\" LIMIT 5"}}' \
  | notion-cli tools call notion-query-data-sources -f -

# --raw prints the full tool result (all content blocks + isError) as JSON;
# the default prints just the text content
notion-cli tools call notion-fetch --args '{"id":"<id>"}' --raw

By default the command prints the tool's text content and exits non-zero if the tool reports an error. Use --raw/-r when you need the structured result.

Configuration

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.

Profiles

Every command accepts --profile <name> (or NOTION_CLI_PROFILE) to scope the OAuth token and official API config to a specific Notion account, so you can keep separate logins for work, home, etc.

# Log in to a named profile
notion-cli auth login --profile work

# Use the profile for a single command
notion-cli page list --profile work

# Pin a profile for the shell session
export NOTION_CLI_PROFILE=work

# Make a profile the default for future invocations
notion-cli auth use work

Profile resolution, highest priority first:

1. --profile <name> flag
2. NOTION_CLI_PROFILE environment variable
3. Active profile from notion-cli auth use <name>
4. Implicit default profile

The default profile keeps using the existing OAuth token path, so existing single-account installs need no migration. notion-cli auth use <name> stores the active profile in the cross-profile config directory.

Profile names must start and end with a lowercase ASCII letter or number. They may contain lowercase letters, numbers, at signs, dots, underscores, and hyphens.

Named profiles store their credentials under ~/.config/notion-cli/profiles/<profile>/{token,config}.json.

notion-cli auth status prints the selected profile and token path, and notion-cli auth list shows all known profiles with OAuth and API-token status.

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
NOTION_CLI_PROFILE	Default profile when --profile is not passed

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.