docs: update all documentation for new commands shipped in v0.13.0

.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**
 
 ---
 
@@ -143,6 +146,27 @@ Supported property types: `title`, `rich_text`, `number`, `select`, `multi_selec
 
 **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
 
 ```bash
@@ -175,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
@@ -338,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"
 ```
 
 ---
@@ -363,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.

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

docs/FEATURE-PARITY.md

@@ -4,7 +4,7 @@
 > This document tracks gaps and serves as a prioritized roadmap for closing them.
 
 **Legend:**
-- **CLI** = `@andrzejchm/notion-cli` (this repo, v0.9.0)
+- **CLI** = `@andrzejchm/notion-cli` (this repo, v0.13.0)
 - **MCP** = Official Notion MCP server
 
 ---
@@ -20,15 +20,15 @@
 | Page properties | Read + write via `update --prop` | Full read + write (update any property) | ✅ Parity |
 | Move pages | `move --to` / `--to-db` | Batch move to any parent | ✅ Parity |
 | Duplicate pages | - | Duplicate with async content copy | Gap |
-| Archive/delete | `archive` | Trash pages | ✅ Parity |
+| Archive/delete | `archive` (pages + databases), `delete-block` | Trash pages | ✅ Parity |
 | Database create | `db create --prop` syntax | SQL DDL `CREATE TABLE` syntax | Partial |
-| Database schema update | Read-only schema | `ADD/DROP/RENAME/ALTER COLUMN` via DDL | Gap |
+| Database schema update | `--add-prop, --remove-prop, --rename-prop, --set-options` | `ADD/DROP/RENAME/ALTER COLUMN` via DDL | Partial |
 | Database views | - | Create + update 10 view types with DSL | Gap |
 | Comments | Page-level + block-level + thread replies, list with discussion IDs | Page-level + inline (selection-anchored) + reply to thread + rich text | Partial |
 | Users | List all | List + search + fetch by ID + fetch self | Partial |
 | Teams | - | List teamspaces + search | Gap |
 | Create pages in DB | `create-page --parent <db>` with `--prop` | Full property support, date/place/checkbox expanded formats | ✅ Parity |
-| Batch operations | - | Create up to 100 pages, move up to 100 pages | Gap |
+| Batch operations | `db update-rows` with filter + dry-run | Create up to 100 pages, move up to 100 pages | Partial |
 | Icon / Cover | `--icon` / `--cover` on `create-page` | Set emoji/image icon + cover on create and update | Partial |
 
 ---
@@ -79,11 +79,10 @@ These gaps directly limit what an AI agent can accomplish through the CLI compar
 **CLI:** `notion move <ids...> --to <page-id>` or `notion move <ids...> --to-db <database-id>`. Supports multiple page IDs as variadic arguments.
 **Status:** Shipped in v0.11.0.
 
-#### 8. Update database schema
+#### 8. ✅ Update database schema (shipped v0.13.0)
 **MCP:** `ADD COLUMN`, `DROP COLUMN`, `RENAME COLUMN`, `ALTER COLUMN SET` via DDL.
-**CLI:** Read-only schema via `notion db schema`.
-**Why:** Evolving database structure (adding a new status option, renaming a field) without leaving the terminal.
-**Suggested command:** `notion db alter <id> --add "Priority SELECT(High,Medium,Low)" --rename "Status:Project Status"`
+**CLI:** `notion db update <id> --add-prop "Priority:number"` / `--remove-prop` / `--rename-prop` / `--set-options` / `--title`.
+**Status:** Shipped in v0.13.0. Covers add/remove/rename properties and select option management. Does not support relation, rollup, formula, or unique_id types.
 
 #### 9. ✅ Multi-operation content editing (shipped v0.9.0)
 **MCP:** `update_content` accepts an array of `{ old_str, new_str }` pairs (up to 100) in a single call, with `replace_all_matches` option.
@@ -96,53 +95,63 @@ These gaps directly limit what an AI agent can accomplish through the CLI compar
 **Why:** Templating workflows — copy a template page to start a new project/sprint.
 **Suggested command:** `notion duplicate <id>`
 
+#### 11. ✅ Batch update-rows (shipped v0.13.0)
+**MCP:** Create up to 100 pages in a single call.
+**CLI:** `notion db update-rows <id> --filter "Status=Open" --prop "Priority=High"` — query + batch update with concurrency control. `--dry-run` for safe preview.
+**Status:** Shipped in v0.13.0. Covers batch property updates with filter. Batch page creation (100 pages in one call) is still a gap.
+
+#### 12. ✅ Delete blocks (shipped v0.13.0)
+**MCP:** No direct equivalent (MCP can trash pages but not arbitrary blocks).
+**CLI:** `notion delete-block <id>` — deletes any block via `DELETE /v1/blocks/{block_id}`.
+**Status:** Shipped in v0.13.0. CLI-only feature not available in MCP.
+
 ### Tier 3 - Lower Impact (nice-to-have, niche workflows)
 
-#### 11. Database views (create + update)
+#### 13. Database views (create + update)
 **MCP:** 10 view types (table, board, calendar, timeline, gallery, list, form, chart, map, dashboard) with DSL for filters, sorts, grouping.
 **CLI:** No equivalent.
 **Why:** Mostly a UI concern; agents rarely need to create views programmatically. But useful for project setup automation.
 
-#### 12. Page icon and cover
+#### 14. Page icon and cover
 **MCP:** Set emoji/custom emoji/image URL as icon; set image URL as cover on create and update.
 **CLI:** No equivalent.
 **Why:** Cosmetic but helps agents create polished pages. Low effort to add as flags.
 **Suggested flags:** `--icon "🚀"` / `--cover "https://..."`
 
-#### 13. Teams / teamspaces listing
+#### 15. Teams / teamspaces listing
 **MCP:** `get-teams` with name search.
 **CLI:** No equivalent.
 **Why:** Rarely needed by agents. Useful for workspace discovery in large organizations.
 **Suggested command:** `notion teams`
 
-#### 14. Scoped search (within page / database / teamspace)
+#### 16. Scoped search (within page / database / teamspace)
 **MCP:** `page_url`, `data_source_url`, `teamspace_id` parameters scope search.
 **CLI:** Global search only.
 **Why:** Useful for agents working within a specific project area, but global search + filtering usually suffices.
 **Suggested flags:** `--within <id>`
 
-#### 15. Page verification
+#### 17. Page verification
 **MCP:** `update_verification` — mark pages as verified with optional expiry (Business/Enterprise only).
 **CLI:** No equivalent.
 **Why:** Enterprise-only feature, limited audience.
 
-#### 16. Template application
+#### 18. Template application
 **MCP:** Apply database templates on create and update (template content is async).
 **CLI:** No equivalent.
 **Why:** Useful for standardized page creation but requires database template discovery first.
 **Suggested flags:** `--template <template-id>`
 
-#### 17. Batch page creation
+#### 19. Batch page creation
 **MCP:** Create up to 100 pages in a single call.
 **CLI:** One page per invocation.
 **Why:** Performance optimization for bulk workflows. Can be scripted with shell loops for now.
 
-#### 18. Advanced user lookup
+#### 20. Advanced user lookup
 **MCP:** Search users by name/email, fetch by ID, fetch authenticated user (`self`).
 **CLI:** `notion users` lists all, no search or lookup.
 **Suggested flags:** `notion users --search "john"` / `notion users --id <uuid>` / `notion users --me`
 
-#### 19. Fetch page discussions inline
+#### 21. Fetch page discussions inline
 **MCP:** `include_discussions: true` on fetch shows discussion anchors in page content; `get-comments` with `include_all_blocks`, `include_resolved`.
 **CLI:** `notion comments` shows page-level comments only, no block-level discussions, no resolved filter.
 **Suggested flags:** `--all-blocks` / `--include-resolved`
@@ -172,11 +181,11 @@ The CLI isn't just chasing MCP parity — it has unique strengths:
 - Tier 1 items (1-4) should be tackled before any Tier 2 work
 - Items 1 and 2 can share infrastructure (property value parsing, `--prop` flag syntax)
 - Item 3 (archive) is likely a small addition once property updates work (archive is a property)
-- Items 6 and 8 (database create/alter) can share a schema DSL parser
+- Items 6 (database create) and 8 (database alter) are both shipped and share property definition parsing
 - The CLI should NOT try to replicate MCP's SQL DDL syntax — a simpler flag-based approach fits CLI ergonomics better
 
 ---
 
-*Last updated: 2026-03-24*
-*CLI version compared: 0.9.0*
+*Last updated: 2026-04-08*
+*CLI version compared: 0.13.0*
 *MCP version compared: Official Notion MCP (2026-03)*