notion

Category: Content & Multimedia | Uploader: lox | Downloads: 0 | Version: v1.0（Latest）
Manage Notion pages, databases, and comments from the command line. Search, view, create, and edit content in your Notion workspace.
Changelog: Source: GitHub https://github.com/lox/notion-cli
Directory Structure

Current level: tree/main/skills/notion/
📄 SKILL.md 7.0 KB
SKILL.md

---
name: notion
description: Manage Notion pages, databases, and comments from the command line. Search, view, create, and edit content in your Notion workspace.
allowed-tools: Bash(notion-cli:*)
---

# Notion CLI

A CLI to manage Notion from the command line, using Notion's remote MCP server.

## Prerequisites

The `notion-cli` command must be available on PATH. To check:

```bash
notion-cli version
```

If not installed:

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

Or see: https://github.com/lox/notion-cli

## Authentication

The CLI uses OAuth authentication. On first use, it opens a browser for authorization:

```bash
notion-cli auth login      # Authenticate with Notion
notion-cli auth status     # Check authentication status
notion-cli auth refresh    # Refresh token if status shows expired token
notion-cli auth logout     # Clear credentials
```

For CI/headless environments, set `NOTION_ACCESS_TOKEN` environment variable.

## Available Commands

```
notion-cli auth            # Manage authentication
notion-cli page            # Manage pages (list, view, create, upload, edit)
notion-cli db              # Manage databases (list, query, create entries)
notion-cli search          # Search the workspace
notion-cli comment         # Manage comments (list, create)
notion-cli tools           # List available MCP tools
```

## Common Operations

### Search

```bash
notion-cli search "meeting notes"           # Search workspace
notion-cli search "project" --limit 5       # Limit results
notion-cli search "query" --json            # JSON output
```

### Pages

All page commands accept a **URL**, **name**, or **ID** to identify pages.

```bash
# List pages
notion-cli page list
notion-cli page list --limit 10
notion-cli page list --json

# View a page (renders as markdown in terminal)
notion-cli page view <page>
notion-cli page view <page> --no-comments    # Hide page and block comments
notion-cli page view <page> --raw            # Show raw Notion markup
notion-cli page view <page> --json           # JSON output
notion-cli page view "Meeting Notes"         # By name
notion-cli page view https://notion.so/...   # By URL

# Create a page
notion-cli page create --title "New Page"
notion-cli page create --title "Doc" --content "# Heading\n\nContent here"
notion-cli page create --title "Child" --parent "Engineering"   # Parent by name
notion-cli page create --title "Child" --parent <page-id>       # Parent by ID

# Upload a markdown file as a page
notion-cli page upload ./document.md
notion-cli page upload ./doc.md --title "Custom Title"
notion-cli page upload ./doc.md --parent "Parent Page Name"
notion-cli page upload ./doc.md --parent-db <db-id>         # Upload as database entry

# Sync a markdown file (create or update)
# First run creates the page and writes notion-id to the file's frontmatter.
# Subsequent runs update the page content using the stored notion-id.
notion-cli page sync ./document.md
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 --title "Custom Title"

# Edit a page
notion-cli page edit <page> --replace "New content"
notion-cli page edit <page> --find "old text" --replace-with "new text"
notion-cli page edit <page> --find "section" --append "additional content"
```

`page view` shows open page-level comments and inline block discussions by default. Inline discussions are rendered beside their anchor text, with the anchor wrapped in `[[...]]` and the discussion shown immediately below it. Use `--no-comments` when you only want the page body, `--raw` to inspect the original Notion markup, and `--json` when an agent needs the page plus the `Comments` array.

### Edit mode guardrails

`page edit` supports these mutually exclusive modes:

1. `--replace "..."` for full-page replacement.
2. `--find "..." --replace-with "..."` for targeted replacement.
3. `--find "..." --append "..."` for append-after-match.

When a targeted edit fails (for example MCP validation errors), fall back to full replacement by fetching content, editing locally, then applying `--replace`.

### Databases

All database commands accept a **URL**, **name**, or **ID** to identify databases.

```bash
# List databases
notion-cli db list                          # List databases
notion-cli db list -q "project"             # Filter by name
notion-cli db list --json

# Query a database
notion-cli db query <database-url-or-id>    # Query a database
notion-cli db query <id> --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 "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    # Body from file
notion-cli db create <database> -t "Title" --json
```

**Property format:** Use `--prop Key=Value` for text/status properties. Date properties use expanded keys: `--prop "date:Date Field:start=2026-01-15"`.

### Comments

```bash
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
notion-cli comment list "Meeting Notes"     # Resolve a page by name

notion-cli comment create <page> --content "Great work!"
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 `--resolved` is passed.

## Output Formats

Most commands support `--json` for machine-readable output:

```bash
notion-cli page list --json | jq '.[0].url'
notion-cli search "api" --json | jq '.[] | .title'
```

## Tips for Agents

1. **Search first** - Use `notion-cli search` to find pages before operating on them
2. **Use URLs, names, or IDs** - All page commands and comment commands resolve pages from any of these forms
3. **Explicit parent types** - Use `--parent` for page parents, `--parent-db` for database parents on `page sync`/`page upload`
4. **Query databases first** - Use `notion-cli db query <id>` to see the schema and property types before creating entries
5. **Check --help** - Every command has detailed help: `notion-cli page edit --help`
6. **Inline comments by default** - `page view` includes open page comments and inline block discussions unless `--no-comments` is set
7. **Raw output** - Use `--raw` with `page view` to see the original Notion markup
8. **JSON for parsing** - Use `--json` when you need to extract specific fields, including the `Comments` array from `page view`
9. **Auth preflight** - Run `notion-cli auth status --json` before a multi-step workflow and refresh/login if needed
10. **Error handling** - If a targeted `page edit` call fails, rerun with `--replace` as a safe fallback
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
notion

Directory Structure

SKILL.md

Report

Notice
