@andrzejchm/notion-cli 0.12.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, attaching files, 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.12.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, attach files, 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.12.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
 
@@ -36,6 +36,9 @@ Pages must be shared with your integration: open page → `⋯` → **Add connec
 - `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**
 
 ---
 
@@ -116,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
@@ -150,7 +199,8 @@ 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
@@ -279,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"
 
@@ -308,6 +363,21 @@ notion append "$PAGE_ID" -m "## Data Analysis\nSee attached CSV:" --file ./expor
 
 # 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"
 ```
 
 ---
@@ -333,3 +403,9 @@ notion update "$PAGE_ID" --icon ./logo.png
 **`--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,8 +96,10 @@ 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 |
@@ -107,7 +109,8 @@ notion ls
 | `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 |
@@ -164,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