using-notion-cli

name	using-notion-cli
description	Use when reading or writing Notion pages, searching a Notion workspace, querying or creating Notion databases, updating database schemas, batch-updating database rows, appending or editing page content, creating pages, updating page properties, moving pages, attaching files, adding comments, deleting blocks, or archiving pages and databases — via the `notion` CLI tool in the terminal.

Overview - skill version 0.13.0

notion is a CLI tool for reading and writing Notion content from the terminal or agent workflows. Use it any time you need to interact with Notion: read pages, search, query databases, create and update database schemas, batch-update rows, append or edit content, create pages, update properties, move pages, post comments, attach files, delete blocks, or archive pages and databases.

Version check: Run notion --version. If your installed version is older than 0.13.0, update with npm install -g @andrzejchm/notion-cli and refresh this skill with notion skill.

Setup

Install once:

npm install -g @andrzejchm/notion-cli
notion auth login   # interactive setup — choose OAuth or integration token

Or set env var (preferred for CI/agents):

export NOTION_API_TOKEN=ntn_your_token_here

Get token: https://www.notion.so/profile/integrations/internal

Pages must be shared with your integration: open page → ⋯ → Add connections.

Integration capabilities (set at notion.so/profile/integrations/internal → your integration → Capabilities):

• Read-only commands: Read content only
• notion append, notion append --after, notion create-page (page parent): also need Insert content
• notion create-page --parent <db>: also need Insert content + database must be shared with integration
• notion edit-page: also need Update content + Insert content
• notion attach: also need Insert content
• notion comment: also need Read comments + Insert comments
• notion db update: also need Update content
• notion db update-rows: also need Read content + Update content
• notion delete-block: also need Update content

---

Authentication

Two auth methods are available. If both are configured, OAuth takes precedence.

Method	Command	Attribution	Notes
Interactive setup	notion auth login	—	Guides you to choose; TTY required
OAuth user login	select "OAuth user login" in notion auth login	Your Notion account	Browser required; --manual for headless
Integration token	select "Integration token" in notion auth login	Integration bot	Works in CI/headless; must connect integration to pages

notion auth login                    # interactive selector — OAuth or integration token
notion auth login --manual           # headless OAuth (prints URL, paste redirect back)
notion auth status                   # show current auth state
notion auth logout                   # remove a profile (interactive selector)
notion auth logout --profile <name>  # remove specific profile directly
notion auth list                     # list all saved profiles
notion auth use <name>               # switch active profile
notion --profile <name> <command>    # use a specific profile for one command

Headless/CI agents: Use NOTION_API_TOKEN=<token> env var — overrides all config, no TTY needed.

---

Output Modes

Context	Default	Override
Terminal (TTY)	Formatted tables	--json
Piped / agent	Plain text tables	--json

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

Pipe any command to get JSON:

notion search "query" | jq '.[0].id'
notion ls | jq '.[] | select(.type == "database")'

---

Commands

Search & Discovery

notion search "query"                    # search all pages/databases by title
notion search "query" --type page        # pages only
notion search "query" --type database    # databases only
notion search "query" --sort asc         # sort by last edited time (asc or desc)
notion ls                                # list everything accessible to integration
notion ls --sort desc                    # sort by last edited time
notion users                             # list workspace members
notion comments <id|url>                 # list page comments
notion open <id|url>                     # open in browser

Reading Pages

notion read <id|url>          # markdown (always, even when piped)
notion read <id|url> --json   # raw Notion JSON block tree

Database Operations

notion db schema <id|url>                             # inspect properties + valid values
notion db query <id|url>                              # all rows
notion db query <id|url> --filter "Status=Done"       # filter (repeatable)
notion db query <id|url> --sort "Created:desc"        # sort (repeatable)
notion db query <id|url> --columns "Title,Status"     # limit columns
notion db query <id|url> --json | jq '.[] | .properties'

notion db create --parent <page-id|url> --title "My Database"  # create a new database
notion db create --parent <page-id|url> --title "Tasks" \
  --prop "Status:select:To Do,In Progress,Done" \
  --prop "Priority:select:High,Medium,Low" \
  --prop "Due:date:" \
  --prop "Notes:rich_text:"                                    # with property definitions

Creating Databases with Properties

Use --prop "Name:type[:options]" (repeatable) to define columns when creating a database.

# Database with select, date, and text properties
notion db create --parent "$PAGE_ID" --title "Project Tracker" \
  --prop "Status:select:To Do,In Progress,Done" \
  --prop "Priority:select:High,Medium,Low" \
  --prop "Due:date:" \
  --prop "Notes:rich_text:"

# Minimal — title column is added automatically if not specified
notion db create --parent "$PAGE_ID" --title "Simple List"

Supported property types: title, rich_text, number, select, multi_select, status, date, checkbox, url, email, phone_number, people, files, created_time, last_edited_time.

Important: After creating a database, use notion search "DB Title" --type database to find the database ID for subsequent operations. The ID returned by db create is a URL-based ID that may differ from the API-accessible database ID.

Updating Database Schema

notion db update <id|url> --add-prop "Priority:number"                     # add a number property
notion db update <id|url> --add-prop "Severity:select:Low,Medium,High"     # add select with options
notion db update <id|url> --remove-prop "Old Column"                       # remove a property
notion db update <id|url> --rename-prop "Status:Project Status"            # rename a property
notion db update <id|url> --set-options "Priority:P1,P2,P3"               # replace select options
notion db update <id|url> --title "New Database Title"                     # update title
notion db update <id|url> --add-prop "URL:url" --remove-prop "Notes"      # multiple ops in one call

Batch Updating Database Rows

notion db update-rows <id|url> --filter "Status=Open" --prop "Priority=P3"    # update filtered rows
notion db update-rows <id|url> --prop "Status=Closed"                         # update ALL rows
notion db update-rows <id|url> --filter "Status=Done" --prop "Priority=Low" --dry-run  # preview
notion db update-rows <id|url> --filter "Category=Bug" --prop "Status=Done" --json     # JSON output

Write Operations

notion append <id|url> -m "## Heading\nParagraph text"   # append markdown blocks to a page
notion append <id|url> -m "$(cat notes.md)"              # append file contents
notion append <id|url> --file screenshot.png             # attach a local file
notion append <id|url> -m "See results:" --file chart.png  # markdown + file attachment
notion append <id|url> --file a.png --file b.pdf         # multiple files (repeatable)

notion create-page --parent <page-id|url> --title "Title"               # child page under a page
notion create-page --parent <page-id|url> --title "Title" -m "# Hello"  # with markdown body
echo "# Content" | notion create-page --parent <page-id|url> --title "Title"  # from stdin
notion create-page --parent <page-id|url> --title "Report" --file report.pdf  # with file attachment
notion create-page --parent <page-id|url> --title "Notes" -m "# Agenda" --file slides.pdf --file notes.txt

# Create entry in a database (auto-detected from parent ID)
notion create-page --parent <db-id|url> --title "New Task"
notion create-page --parent <db-id|url> --title "Task" --prop "Status=To Do" --prop "Priority=High"
notion create-page --parent <db-id|url> --title "Task" --prop "Due=2026-04-01" -m "# Details"

# Icon and cover (emoji, URL, or local file path)
notion create-page --parent <id|url> --title "Page" --icon "🚀"
notion create-page --parent <id|url> --title "Page" --icon ./logo.png              # upload local file as icon
notion create-page --parent <id|url> --title "Page" --cover "https://example.com/img.jpg"
notion create-page --parent <id|url> --title "Page" --cover ./banner.jpg           # upload local file as cover

URL=$(notion create-page --parent <id|url> --title "Summary" -m "...")   # capture URL

notion comment <id|url> -m "Reviewed and approved."                  # add comment to a page
notion comment <id|url> -m "Reply" --reply-to <discussion-id>        # reply to a discussion thread
notion comment <id|url> -m "Note" --block <block-id>                 # comment on a specific block

notion archive <id|url>                                              # move page or database to trash
notion delete-block <id|url>                                         # delete a block (inline db, paragraph, etc.)

notion move <ids|urls...> --to <id|url>                              # move pages to a new parent page
notion move <ids|urls...> --to-db <id|url>                           # move pages to a database parent

File Attachments

Upload local files to Notion and attach them as blocks (image, file, PDF, audio, video). Block type is auto-detected from file extension. Files ≤20 MB upload in one request; larger files are chunked automatically.

notion attach <id|url> screenshot.png                                # attach a single file
notion attach <id|url> report.pdf data.csv image.png                 # attach multiple files
notion attach <id|url> diagram.png --caption "Architecture diagram"  # with caption
notion attach <id|url> file.svg --type image                         # override auto-detected type

Flag	Description
--caption <text>	Caption for the file block(s)
--type <type>	Override block type (image|file|pdf|audio|video)
--json	Output JSON response

The --file <path> flag (repeatable) is also available on notion append and notion create-page for inline file attachment alongside markdown content.

Updating Page Properties

notion update <id|url> --prop "Status=Done"                      # set a single property
notion update <id|url> --prop "Status=Done" --prop "Priority=1"  # multiple properties
notion update <id|url> --title "New Title"                       # set the title
notion update <id|url> --prop "Due=2026-04-01"                   # set a date
notion update <id|url> --prop "Tags=bug,urgent"                  # multi-select (comma-separated)
notion update <id|url> --prop "Done=true"                        # checkbox (true/yes/false/no)
notion update <id|url> --prop "Status="                          # clear a property (empty value)

Supported types: title, rich_text, select, status, multi_select, number, checkbox, url, email, phone_number, date, files.

# Files property — local file paths or URLs (comma-separated for multiple)
notion update <id|url> --prop "Attachments=./report.pdf"                    # upload local file
notion update <id|url> --prop "Attachments=https://example.com/file.pdf"    # external URL
notion update <id|url> --prop "Attachments=./a.pdf,./b.png"                 # multiple files

Note: Setting a files property replaces all existing files (Notion API behavior). To keep existing files, re-include them in the value.

Surgical Editing

Search-and-replace specific text, replace the full page, or insert content at a specific location.

# Search-and-replace: find text and replace it
notion edit-page <id|url> --find "old text" --replace "new text"

# Multiple search-and-replace operations in one call
notion edit-page <id|url> --find "old1" --replace "new1" --find "old2" --replace "new2"

# Replace all occurrences (not just the first match)
notion edit-page <id|url> --find "TODO" --replace "DONE" --all

# Replace an entire page's content
notion edit-page <id|url> -m "# Replacement\nNew full-page content"

# Pipe replacement content from a file
cat updated-section.md | notion edit-page <id|url>

# Allow deletion of child pages/databases during replace
notion edit-page <id|url> -m "## Clean Slate" --allow-deleting-content

# Append after a matched section (inserts new blocks right after the match)
notion append <id|url> -m "New content" --after "## Status...end of status"

--range (deprecated): The --range flag still works for backward compatibility but uses the older replace_content_range API. Prefer --find/--replace for targeted edits.

---

ID Formats

All commands accept any of:

• abc123def456789012345678901234ab (32-char hex)
• abc123de-f456-7890-1234-5678901234ab (UUID)
• https://www.notion.so/workspace/Page-Title-abc123 (full URL)

---

Agent Patterns

# Find page by title, read it
PAGE_ID=$(notion search "Meeting Notes" --type page | jq -r '.[0].id')
notion read "$PAGE_ID"

# Get database ID, then query with filter
DB_ID=$(notion search "Project Tracker" --type database | jq -r '.[0].id')
notion db query "$DB_ID" --filter "Status=In Progress" | jq '.[] | .properties'

# Always check schema before filtering (see valid property names/values)
notion db schema "$DB_ID"
notion db query "$DB_ID" --filter "Status=Done"

# Extract page section
notion read "$PAGE_ID" | grep -A 10 "## Action Items"

# Summarize a page and append the summary back
SUMMARY=$(notion read "$PAGE_ID" | your-summarize-command)
notion append "$PAGE_ID" -m "## AI Summary\n$SUMMARY"

# Create a page and capture its URL for further use
URL=$(notion create-page --parent "$PAGE_ID" --title "Report $(date +%Y-%m-%d)" -m "# Report\n...")
echo "Created: $URL"

# Pipe command output into a new page
my-report-command | notion create-page --parent "$PAGE_ID" --title "Auto Report"

# Surgically update specific text on a page
# 1. Read the page to find the text you want to change
notion read "$PAGE_ID"
# 2. Use --find/--replace to swap specific text
notion edit-page "$PAGE_ID" --find "Status: In Progress" --replace "Status: Done"

# Multiple replacements in one call
notion edit-page "$PAGE_ID" \
  --find "Status: In Progress" --replace "Status: Done" \
  --find "Blocked: yes" --replace "Blocked: none"

# Create a database with typed columns, then add entries
notion db create --parent "$PAGE_ID" --title "Sprint Tasks" \
  --prop "Status:select:To Do,In Progress,Done" \
  --prop "Priority:select:High,Medium,Low" \
  --prop "Due:date:" --prop "Notes:rich_text:"
# Use search to get the API-accessible database ID (may differ from db create output)
DB_ID=$(notion search "Sprint Tasks" --type database | jq -r '.[0].id')
notion db schema "$DB_ID"   # verify property names and valid values
notion create-page --parent "$DB_ID" --title "Fix login bug" \
  --prop "Status=To Do" --prop "Priority=High" --prop "Due=2026-04-15"

# Insert a new sub-section after an existing section
notion append "$PAGE_ID" -m "## New Sub-section\nContent here" \
  --after "## Existing Section...last line of section"

# Move pages to a different parent
ARCHIVE_ID=$(notion search "Archive" --type page | jq -r '.[0].id')
notion move "$PAGE_ID" --to "$ARCHIVE_ID"

# Move multiple pages into a database
notion move page1-id page2-id --to-db "$DB_ID"

# Attach a generated screenshot to a documentation page
notion attach "$PAGE_ID" ./screenshot.png --caption "Current UI state"

# Create a report page with attached artifacts
notion create-page --parent "$PAGE_ID" --title "Build Report $(date +%Y-%m-%d)" \
  -m "# Build Results\nAll tests passed." --file ./test-results.pdf --file ./coverage.png

# Append analysis with supporting data file
notion append "$PAGE_ID" -m "## Data Analysis\nSee attached CSV:" --file ./export.csv

# Upload a local file as icon for a page
notion update "$PAGE_ID" --icon ./logo.png

# Modify a database schema — add a column after creation
notion db update "$DB_ID" --add-prop "Sprint:select:S1,S2,S3"

# Clean up stale select options
notion db update "$DB_ID" --set-options "Status:To Do,In Progress,Done"

# Batch close all "In Progress" tasks
notion db update-rows "$DB_ID" --filter "Status=In Progress" --prop "Status=Done"

# Preview a batch update before applying
notion db update-rows "$DB_ID" --filter "Priority=Low" --prop "Status=Archived" --dry-run

# Delete an inline database from a page
notion delete-block "$BLOCK_ID"

---

Troubleshooting

404 / page not found — Share the page with your integration: page → ⋯ → Add connections.

401 / unauthorized — Run notion auth login or set NOTION_API_TOKEN.

Search returns nothing — Search is title-only. Page must be shared with integration.

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

notion auth login requires TTY — Use NOTION_API_TOKEN env var in agents, or use notion auth login --manual for headless OAuth.

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

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

notion edit-page returns "Insufficient permissions" — Enable Update content in integration capabilities.

--find text not found — Run notion read <id> to see the exact page content. The --find value must match text on the page exactly.

--after selector not found — Run notion read <id> to see the exact page content. The selector must match real text: "start...end" with ~10 chars from the beginning and end of the target range.

notion db update fails with "Property not found" — Run notion db schema <id> to see exact property names. For --rename-prop and --set-options, the property must exist.

notion db update-rows updates 0 rows — Check that your --filter matches rows: run notion db query <id> --filter "..." first.

notion archive fails for a database — Try using the data source ID (from notion db schema <id> --json) instead of the database page ID.