@andrzejchm/notion-cli 0.11.0 → 0.13.0

package/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)*

package/docs/README.agents.md

@@ -82,6 +82,162 @@ To update the skill file, re-download it from the URL in step 2 to the same loca
 
 ## Commands Reference
 
+### `notion attach <id|url> <file> [files...]`
+
+Upload and attach local files to a Notion page as file blocks.
+
+```bash
+# Attach a single image
+notion attach "$PAGE_ID" screenshot.png
+
+# Attach multiple files
+notion attach "$PAGE_ID" report.pdf data.csv image.png
+
+# Add a caption to all attached files
+notion attach "$PAGE_ID" diagram.png --caption "Architecture diagram"
+
+# Override auto-detected block type
+notion attach "$PAGE_ID" file.svg --type image
+
+# Output JSON response
+notion attach "$PAGE_ID" file.pdf --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--caption <text>` | Caption for the file block(s) |
+| `--type <type>` | Override auto-detected block type (`image\|file\|pdf\|audio\|video`) |
+| `--json` | Output JSON response |
+
+Block type is auto-detected from the file extension. Images (png, jpg, gif, webp, svg, etc.) become `image` blocks, audio files become `audio` blocks, video files become `video` blocks, PDFs become `pdf` blocks, and everything else becomes a `file` block.
+
+Files ≤20 MB are uploaded in a single request. Larger files are split into 20 MB chunks automatically.
+
+Required integration capabilities: **Read content**, **Insert content**
+
+### `notion append <id|url>` — `--file` flag
+
+The `append` command accepts a repeatable `--file <path>` option to attach local files after the markdown content:
+
+```bash
+# Append markdown and attach a file
+notion append "$PAGE_ID" -m "See attached screenshot:" --file screenshot.png
+
+# Attach files without any markdown (files only)
+notion append "$PAGE_ID" --file image.png --file data.csv
+
+# Pipe markdown and attach a file
+echo "# Report" | notion append "$PAGE_ID" --file report.pdf
+```
+
+### `notion create-page` — `--file` flag
+
+The `create-page` command accepts a repeatable `--file <path>` option to attach local files after the page is created:
+
+```bash
+# Create a page and attach a PDF
+notion create-page --parent "$PAGE_ID" --title "Report" --file report.pdf
+
+# Create a page with markdown body and attached files
+notion create-page --parent "$PAGE_ID" --title "Meeting Notes" -m "# Agenda" --file slides.pdf --file notes.txt
+```
+
+### `notion db create`
+
+Create a new database under a parent page with typed property columns.
+
+```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"
+```
+
+| Flag | Description |
+|------|-------------|
+| `--parent <id\|url>` | Parent page ID or URL (required) |
+| `--title <title>` | Database title (required) |
+| `--prop <definition>` | Property definition (repeatable) |
+| `--json` | Output full JSON response |
+
+**Property syntax:** `Name:type[:options]`
+
+Supported 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.
+
+Required integration capabilities: **Read content**, **Insert content**
+
+### `notion db update <id|url>`
+
+Update database schema — add, remove, or rename properties and manage select options.
+
+```bash
+# Add a new property
+notion db update "$DB_ID" --add-prop "Priority:number"
+
+# Add a select property with options
+notion db update "$DB_ID" --add-prop "Severity:select:Low,Medium,High,Critical"
+
+# Remove a property
+notion db update "$DB_ID" --remove-prop "Old Column"
+
+# Rename a property
+notion db update "$DB_ID" --rename-prop "Status:Project Status"
+
+# Replace all select/multi_select options
+notion db update "$DB_ID" --set-options "Priority:P1,P2,P3"
+
+# Update database title
+notion db update "$DB_ID" --title "Renamed Database"
+
+# Multiple operations in one call
+notion db update "$DB_ID" --add-prop "URL:url" --remove-prop "Notes" --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--add-prop <definition>` | Add a new property (repeatable). Syntax: `Name:type[:options]` |
+| `--remove-prop <name>` | Remove a property (repeatable) |
+| `--rename-prop <old:new>` | Rename a property (repeatable) |
+| `--set-options <prop:opts>` | Replace all select/multi\_select options |
+| `--title <title>` | Update database title |
+| `--json` | Output full JSON response |
+
+Required integration capabilities: **Read content**, **Update content**
+
+### `notion db update-rows <id|url>`
+
+Batch update properties on database rows matching a filter.
+
+```bash
+# Update all rows matching a filter
+notion db update-rows "$DB_ID" --filter "Status=Open" --prop "Priority=High"
+
+# Update all rows (no filter)
+notion db update-rows "$DB_ID" --prop "Status=Closed"
+
+# Dry run — preview affected rows without modifying
+notion db update-rows "$DB_ID" --filter "Category=Bug" --prop "Status=Done" --dry-run
+
+# JSON output with per-row success/error
+notion db update-rows "$DB_ID" --filter "Priority=Low" --prop "Status=Archived" --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--filter <expr>` | Filter rows to update (repeatable, same syntax as `db query --filter`) |
+| `--prop <property=value>` | Property to set on matching rows (repeatable, required) |
+| `--dry-run` | Show matching rows without making changes |
+| `--json` | Output JSON array of `{id, title, success, error?}` objects |
+
+Required integration capabilities: **Read content**, **Update content**
+
 ### `notion search <query>` / `notion ls`
 
 Search or list pages and databases. Both commands support:
@@ -145,7 +301,7 @@ Required integration capabilities: **Read content**, **Update content**
 
 ### `notion archive <id|url>`
 
-Archive (trash) a Notion page.
+Archive (trash) a Notion page or database.
 
 ```bash
 # Archive a page by ID
@@ -156,6 +312,26 @@ notion archive "https://www.notion.so/My-Page-b55c9c91384d452b81dbd1ef79372b75"
 
 # Output the full updated page object as JSON
 notion archive "$PAGE_ID" --json
+
+# Archive a database
+notion archive "$DB_ID"
+```
+
+Required integration capabilities: **Read content**, **Update content**
+
+### `notion delete-block <id|url>`
+
+Delete a block from a page (inline database, paragraph, etc.).
+
+```bash
+# Delete an inline database
+notion delete-block "$BLOCK_ID"
+
+# Delete a block by URL
+notion delete-block "https://www.notion.so/page#blockid"
+
+# Output JSON response
+notion delete-block "$BLOCK_ID" --json
 ```
 
 Required integration capabilities: **Read content**, **Update content**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrzejchm/notion-cli",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Read Notion pages and databases from the terminal. Built for AI agents and developers.",
   "keywords": [
     "notion",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
-    "@notionhq/client": "^5.14.0",
+    "@notionhq/client": "^5.17.0",
     "chalk": "^5.6.0",
     "commander": "^14.0.0",
     "yaml": "^2.8.0"