@andrzejchm/notion-cli 0.11.0 → 0.13.0

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

@@ -1,13 +1,13 @@
 ---
 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, adding comments, or archiving pages — via the `notion` CLI tool in the terminal.
+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.11.0
+## 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, append or edit content, create pages, update properties, move pages, post comments, or archive pages.
+`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.11.0, update with `npm install -g @andrzejchm/notion-cli` and refresh this skill with `notion skill`.
+> **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
 
@@ -34,7 +34,11 @@ Pages must be shared with your integration: open page → `⋯` → **Add connec
 - `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**
 
 ---
 
@@ -115,6 +119,52 @@ 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.
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+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
@@ -122,19 +172,26 @@ notion db create --parent <page-id|url> --title "My Database"  # create a new da
 ```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
+# 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
 
@@ -142,12 +199,32 @@ notion comment <id|url> -m "Reviewed and approved."                  # add comme
 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 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.
+
+```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
@@ -160,7 +237,16 @@ notion update <id|url> --prop "Done=true"                        # checkbox (tru
 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.
+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
 
@@ -243,9 +329,14 @@ 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
+# 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"
 
@@ -259,6 +350,34 @@ 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"
 ```
 
 ---
@@ -284,3 +403,9 @@ notion move page1-id page2-id --to-db "$DB_ID"
 **`--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.

package/README.md

@@ -96,21 +96,48 @@ notion ls
 | `notion open <id\|url>` | Open a page in your browser |
 | `notion read <id\|url>` | Read a page as markdown |
 | `notion db create --parent <id\|url> --title <title>` | Create a new database with property definitions |
+| `notion db update [options] <id\|url>` | Update database schema (add/remove/rename properties, manage options) |
 | `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 db update-rows [options] <id\|url>` | Batch update properties on filtered database rows |
 | `notion users` | List workspace members |
 | `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 |
 | `notion update <id\|url> --prop "Name=Value"` | Update properties on a page |
-| `notion archive <id\|url>` | Archive (trash) a page |
+| `notion archive <id\|url>` | Archive (trash) a page or database |
+| `notion delete-block <id\|url>` | Delete a block by ID or URL |
 | `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 |
 | `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 |
@@ -140,6 +167,28 @@ Property syntax: `Name:type[:options]`. Supported types: `title`, `rich_text`, `
 | `--columns` | `--columns "Title,Status"` | Only show specific columns |
 | `--json` | `--json` | Force JSON output |
 
+### `notion db update` flags
+
+| Flag | Example | Description |
+|------|---------|-------------|
+| `--add-prop <definition>` | `--add-prop "Priority:number"` | Add a new property (repeatable) |
+| `--remove-prop <name>` | `--remove-prop "Old Column"` | Remove a property (repeatable) |
+| `--rename-prop <old:new>` | `--rename-prop "Status:Project Status"` | Rename a property (repeatable) |
+| `--set-options <prop:opts>` | `--set-options "Priority:High,Medium,Low"` | Replace all select/multi\_select options |
+| `--title <title>` | `--title "New DB Name"` | Update database title |
+| `--json` | `--json` | Output full JSON response |
+
+Property syntax for `--add-prop`: same as `notion db create --prop` — `Name:type[:options]`.
+
+### `notion db update-rows` flags
+
+| Flag | Example | Description |
+|------|---------|-------------|
+| `--filter <expr>` | `--filter "Status=Done"` | Filter rows to update (repeatable, same syntax as `db query`) |
+| `--prop <property=value>` | `--prop "Priority=High"` | Property to update (repeatable, required) |
+| `--dry-run` | `--dry-run` | Show matching rows without making changes |
+| `--json` | `--json` | Output JSON array of results |
+
 ---
 
 ## Output Modes
@@ -220,6 +269,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 |