@andrzejchm/notion-cli 0.10.0 → 0.12.0

package/.agents/skills/using-notion-cli/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: using-notion-cli
+description: Use when reading or writing Notion pages, searching a Notion workspace, querying or creating Notion databases, appending or editing page content, creating pages, updating page properties, moving pages, attaching files, adding comments, or archiving pages — via the `notion` CLI tool in the terminal.
+---
+
+## Overview - skill version 0.12.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, append or edit content, create pages, update properties, move pages, post comments, attach files, or archive pages.
+
+> **Version check:** Run `notion --version`. If your installed version is older than 0.12.0, update with `npm install -g @andrzejchm/notion-cli` and refresh this skill with `notion skill`.
+
+## Setup
+
+Install once:
+
+```bash
+npm install -g @andrzejchm/notion-cli
+notion auth login   # interactive setup — choose OAuth or integration token
+```
+
+Or set env var (preferred for CI/agents):
+
+```bash
+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**
+
+---
+
+## 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 |
+
+```bash
+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:
+
+```bash
+notion search "query" | jq '.[0].id'
+notion ls | jq '.[] | select(.type == "database")'
+```
+
+---
+
+## Commands
+
+### Search & Discovery
+
+```bash
+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
+
+```bash
+notion read <id|url>          # markdown (always, even when piped)
+notion read <id|url> --json   # raw Notion JSON block tree
+```
+
+### Database Operations
+
+```bash
+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
+```
+
+### Write Operations
+
+```bash
+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 to trash
+
+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.
+
+```bash
+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
+
+```bash
+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.
+
+```bash
+# 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.
+
+```bash
+# 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
+
+```bash
+# 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 entry with properties
+DB_ID=$(notion search "Tasks" --type database | jq -r '.[0].id')
+notion db schema "$DB_ID"   # check property names and valid values first
+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
+```
+
+---
+
+## 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.

package/README.md

@@ -102,6 +102,7 @@ notion ls
 | `notion comments <id\|url>` | Read page comments |
 | `notion comment [id\|url] -m <text>` | Add a comment to a page, block, or thread |
 | `notion append <id\|url> -m <markdown>` | Append markdown blocks to a page |
+| `notion attach <id\|url> <file> [files...]` | Upload and attach file(s) to a page |
 | `notion edit-page <id\|url> --find <old> --replace <new>` | Search-and-replace text on a page |
 | `notion edit-page <id\|url> -m <markdown>` | Replace entire page content |
 | `notion create-page --parent <id\|url> --title <title>` | Create a new page, prints URL |
@@ -111,6 +112,29 @@ notion ls
 | `notion move <ids\|urls...> --to-db <id\|url>` | Move pages to a database parent |
 | `notion completion bash\|zsh\|fish` | Install shell tab completion |
 
+### `notion attach` flags
+
+| Flag | Example | Description |
+|------|---------|-------------|
+| `--caption <text>` | `--caption "My screenshot"` | Caption for the file block(s) |
+| `--type <type>` | `--type image` | Override auto-detected block type (`image\|file\|pdf\|audio\|video`) |
+| `--json` | `--json` | Output JSON response |
+
+### `notion append` / `notion create-page` — `--file` flag
+
+Both commands accept a repeatable `--file <path>` option to attach local files after the markdown content is written:
+
+```bash
+# Append markdown and attach a file
+notion append "$PAGE_ID" -m "See attached screenshot:" --file screenshot.png
+
+# Create a page with an attached PDF
+notion create-page --parent "$PAGE_ID" --title "Report" --file report.pdf
+
+# Attach multiple files
+notion append "$PAGE_ID" --file image.png --file data.csv
+```
+
 ### `notion search` / `notion ls` flags
 
 | Flag | Example | Description |
@@ -220,6 +244,7 @@ Write commands require additional capabilities — enable in your integration se
 | Command | Required capabilities |
 |---------|----------------------|
 | `notion append` | Read content, Insert content |
+| `notion attach` | Read content, Insert content |
 | `notion create-page` | Read content, Insert content |
 | `notion update` | Read content, Update content |
 | `notion comment` | Read content, Insert content, Read comments, Insert comments |