notion-cli

Read and write Notion pages from your terminal — built for AI coding agents and developers.

# Homebrew (recommended)
brew tap andrzejchm/notion-cli
brew install notion-cli

# npm (alternative)
npm install -g @andrzejchm/notion-cli

notion auth login   # choose your auth method

For AI Agents

Fetch and follow instructions from https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/README.agents.md

Features

• notion search — find any page or database by title
• notion read — render any page as full-fidelity markdown
• notion db query — filter, sort, and select columns from any database
• notion append — append markdown content to an existing page
• notion create-page — create a new page with markdown body, prints URL to stdout
• notion comment — add a comment to a page
• Agent-friendly — plain text tables by default; --json for machine-readable output
• Flexible auth — interactive setup or NOTION_API_TOKEN env var
• Accepts URLs — pass full Notion URLs anywhere an ID is expected

Examples

# Search for a page, then read it
PAGE_ID=$(notion search "Q1 Planning" | jq -r '.[0].id')
notion read "$PAGE_ID"

# Query a database with filters
notion db query "$DB_ID" --filter "Status=In Progress" --sort "Priority:asc"

# Get JSON output for scripting / AI agents
notion db query "$DB_ID" --filter "Status=Done" | jq '.[] | .properties.Title'

# Append markdown blocks to an existing page
notion append "$PAGE_ID" -m "## Summary\nGenerated by AI agent."

# Create a new page and capture its URL
URL=$(notion create-page --parent "$PAGE_ID" --title "Meeting Notes" -m "# Agenda\n- Item 1")
echo "Created: $URL"

# Pipe content to a new page
my-summarize-command | notion create-page --parent "$PAGE_ID" --title "Auto Summary"

# Add a comment to a page
notion comment "$PAGE_ID" -m "Reviewed and approved."

# List everything your integration can access
notion ls

Commands

| Command | Description | |---------|-------------| | notion auth login | Interactive auth setup — choose OAuth or integration token | | notion auth logout | Remove a profile and all its credentials | | notion auth status | Show current auth state | | notion auth list | List all saved profiles | | notion auth use <name> | Switch the active profile | | notion search <query> | Search pages and databases by title | | notion ls | List all accessible pages and databases | | notion open <id\|url> | Open a page in your browser | | notion read <id\|url> | Read a page as markdown | | notion db schema <id\|url> | Show database property schema and valid values | | notion db query <id\|url> | Query database entries with filtering and sorting | | notion users | List workspace members | | notion comments <id\|url> | Read page comments | | notion comment <id\|url> -m <text> | Add a comment to a page | | notion append <id\|url> -m <markdown> | Append markdown blocks to a page | | notion create-page --parent <id\|url> --title <title> | Create a new page, prints URL | | notion completion bash\|zsh\|fish | Install shell tab completion |

notion db query flags

| Flag | Example | Description | |------|---------|-------------| | --filter | --filter "Status=Done" | Filter by property value (repeatable) | | --sort | --sort "Created:desc" | Sort by property (:asc or :desc) | | --columns | --columns "Title,Status" | Only show specific columns | | --json | --json | Force JSON output |

Output Modes

The CLI auto-detects your context:

| Context | Default output | Override | |---------|----------------|----------| | Terminal (TTY) | Formatted tables, colored | --json for raw JSON | | Piped / agent | Plain text tables | --json for raw JSON |

notion read always outputs markdown — in terminal and when piped.

Authentication

Two authentication methods are available. If both are configured, OAuth takes precedence for API calls.

Start with the interactive setup:

notion auth login   # choose OAuth or integration token

Tradeoff comparison

| Method | Best for | Write attribution | Requires | |--------|----------|-------------------|----------| | OAuth user login | Write-heavy workflows, personal use | Your Notion account | Browser (or --manual for headless) | | Integration token | CI, Docker, automated agents | Integration bot | Token from notion.so/profile/integrations | | NOTION_API_TOKEN env var | CI/Docker without config files | Integration bot | Token set in environment |

Priority: NOTION_API_TOKEN env var → OAuth token → integration token (first found wins)

OAuth user login

notion auth login         # interactive selector — choose OAuth
notion auth login --manual  # headless: prints URL, prompts to paste redirect
notion auth status        # show current auth state
notion auth logout        # remove profile and credentials

Comments and pages are attributed to your actual Notion account. Access tokens expire after ~1 hour and are refreshed automatically.

Integration token

notion auth login   # interactive selector — choose "Integration token"

# or: environment variable (CI, Docker, agents — no profile needed)
export NOTION_API_TOKEN=ntn_your_token_here

Works everywhere (CI, headless, agents). Write operations are attributed to the integration bot. You must manually connect the integration to each page (⋯ → Add connections).

Token format: starts with ntn_ (new) or secret_ (legacy integrations).
Get a token: notion.so/profile/integrations/internal

Profile management

notion auth list          # list all profiles
notion auth use <name>    # switch active profile
notion auth logout        # remove a profile (interactive selector)
notion auth logout --profile <name>  # remove specific profile directly

Integration capabilities

Read-only commands (search, read, db query, etc.) need Read content only.

Write commands require additional capabilities — enable in your integration settings (notion.so/profile/integrations/internal → your integration → Capabilities):

| Command | Required capabilities | |---------|----------------------| | notion append | Read content, Insert content | | notion create-page | Read content, Insert content | | notion comment | Read content, Insert content, Read comments, Insert comments |

Troubleshooting

Page not found (404): Share the page with your integration — open the page → ⋯ → Add connections.

Unauthorized (401): Run notion auth login to reconfigure, or check your NOTION_API_TOKEN.

Search returns nothing: Search is title-only. The page must also be shared with your integration.

Empty database query: Run notion db schema <id> first to see valid property names and values.

notion comment returns "Insufficient permissions": Enable Read comments and Insert comments in your integration capabilities: notion.so/profile/integrations/internal → your integration → Capabilities.

notion append / notion create-page returns "Insufficient permissions": Enable Insert content in your integration capabilities.

License

MIT © Andrzej Chmielewski