@andrzejchm/notion-cli 0.7.0 → 0.9.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.6.0)
+- **CLI** = `@andrzejchm/notion-cli` (this repo, v0.8.0)
 - **MCP** = Official Notion MCP server
 
 ---
@@ -13,23 +13,23 @@
 
 | Area | CLI | MCP | Parity |
 |------|-----|-----|--------|
-| Search | Basic keyword | Semantic + AI + connected sources + date/creator filters | Partial |
+| Search | Keyword + sort by last edited | Semantic + AI + connected sources + date/creator filters | Partial |
 | Page read | Markdown via API | Markdown + discussions + transcripts | Partial |
 | Page create | Under pages only | Under pages, databases, data sources; batch; templates; icon/cover | Partial |
 | Page edit | Surgical replace via `--range` | Search-and-replace (multi-op), full replace, template apply, verification | Partial |
-| Page properties | Read-only (db query) | Full read + write (update any property) | Gap |
+| Page properties | Read + write via `update --prop` | Full read + write (update any property) | ✅ Parity |
 | Move pages | - | Batch move to any parent | Gap |
 | Duplicate pages | - | Duplicate with async content copy | Gap |
-| Archive/delete | - | Trash pages | Gap |
+| Archive/delete | `archive` | Trash pages | ✅ Parity |
 | Database create | - | SQL DDL `CREATE TABLE` syntax | Gap |
 | Database schema update | Read-only schema | `ADD/DROP/RENAME/ALTER COLUMN` via DDL | Gap |
 | Database views | - | Create + update 10 view types with DSL | Gap |
-| Comments | Page-level add + list | Page-level + inline (selection-anchored) + reply to thread + rich text | Partial |
+| 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 | - | Full property support, date/place/checkbox expanded formats | 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 |
-| Icon / Cover | - | Set emoji/image icon + cover on create and update | Gap |
+| Icon / Cover | `--icon` / `--cover` on `create-page` | Set emoji/image icon + cover on create and update | Partial |
 
 ---
 
@@ -41,37 +41,33 @@ Ordered by impact for AI-agent workflows first, then developer productivity.
 
 These gaps directly limit what an AI agent can accomplish through the CLI compared to using MCP directly.
 
-#### 1. Update page properties
+#### 1. ✅ Update page properties (shipped v0.7.0)
 **MCP:** `update_properties` command — set title, status, dates, select, people, checkbox, numbers, etc. Supports `null` to clear.
-**CLI:** No equivalent. Can only read properties via `db query`.
-**Why first:** AI agents frequently need to update task status, dates, assignees. This is the single most impactful missing write operation.
-**Suggested command:** `notion update <id> --prop "Status=Done" --prop "Priority=High"`
+**CLI:** `notion update <id> --prop "Status=Done"` — supports title, rich_text, select, status, multi_select, number, checkbox, url, email, phone_number, date.
+**Status:** Shipped in v0.7.0.
 
-#### 2. Create pages in databases (with properties)
+#### 2. ✅ Create pages in databases (with properties) (shipped v0.8.0)
 **MCP:** `create-pages` supports `data_source_id` parent with full property map including expanded date, place, checkbox formats.
-**CLI:** `create-page` only supports `page_id` parent with title + markdown body. Cannot create database entries.
-**Why second:** Agents need to create tasks, tickets, and records in databases — not just child pages.
-**Suggested command:** `notion create-page --parent <db-id> --title "Task" --prop "Status=To Do" --prop "Due=2026-04-01"`
+**CLI:** `notion create-page --parent <db-id> --title "Task" --prop "Status=To Do"` — auto-detects database vs page parent. Supports `--icon` and `--cover`.
+**Status:** Shipped in v0.8.0.
 
-#### 3. Archive / trash pages
+#### 3. ✅ Archive / trash pages (shipped v0.9.0)
 **MCP:** `update-page` with property changes or page operations; `update_data_source` with `in_trash: true`.
-**CLI:** No equivalent.
-**Why third:** Agents need to clean up after themselves — archive completed tasks, delete draft pages.
-**Suggested command:** `notion archive <id>` / `notion delete <id>`
+**CLI:** `notion archive <id>` — archives (trashes) a page. Supports `--json` for full page output.
+**Status:** Shipped in v0.9.0.
 
-#### 4. Search filters (date range, creator)
+#### 4. Search filters (date range, creator) — partially addressed
 **MCP:** `created_date_range` (start/end dates), `created_by_user_ids` filter, scoped search within page/database/teamspace.
-**CLI:** Keyword-only search with `--type` filter.
-**Why important:** Agents searching for "recent" items or "my tasks" need date and creator filters to get relevant results without scanning everything.
-**Suggested flags:** `--created-after`, `--created-before`, `--created-by`
+**CLI:** Keyword search with `--type` filter and `--sort asc|desc` (sort by last edited time).
+**Status:** `--sort` added in v0.9.0. Date range and creator filters are **blocked** — the MCP server uses an internal Notion API not accessible to integration tokens. The public search endpoint only supports `sort` as an additional parameter.
+**Remaining gap:** `--created-after`, `--created-before`, `--created-by` cannot be implemented with the public API.
 
 ### Tier 2 - Medium Impact (power-user and advanced agent workflows)
 
-#### 5. Inline / anchored comments
+#### 5. Inline / anchored comments — partially shipped
 **MCP:** `selection_with_ellipsis` targets a specific block; `discussion_id` replies to existing threads. Rich text with mentions, dates, links.
-**CLI:** Page-level comments only. Plain text only.
-**Why:** Agents doing code/doc review need to comment on specific sections, not just drop a page-level note. Thread replies keep conversations organized.
-**Suggested flags:** `notion comment <id> -m "text" --anchor "## Section...content"` / `--reply-to <discussion-id>`
+**CLI:** Thread replies (`--reply-to <discussion-id>`) and block-level comments (`--block <block-id>`) shipped. Discussion IDs shown in `notion comments` list output. Inline text-selection anchoring is not available in the public API. Plain text only.
+**Remaining gap:** Rich text (mentions, dates, links) and inline text-selection anchoring (`selection_with_ellipsis`) — the latter requires internal API access.
 
 #### 6. Create databases
 **MCP:** `CREATE TABLE` DDL with full type system (select, relation, rollup, formula, unique_id, etc.).
@@ -185,5 +181,5 @@ The CLI isn't just chasing MCP parity — it has unique strengths:
 ---
 
 *Last updated: 2026-03-23*
-*CLI version compared: 0.6.0*
+*CLI version compared: 0.8.0*
 *MCP version compared: Official Notion MCP (2026-03)*

package/docs/README.agents.md

@@ -81,6 +81,27 @@ curl -fsSL https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/ski
 
 ## Commands Reference
 
+### `notion search <query>` / `notion ls`
+
+Search or list pages and databases. Both commands support:
+
+```bash
+# Sort results by last edited time
+notion search "meeting notes" --sort desc
+notion ls --sort asc
+
+# Filter by type
+notion search "Q1" --type page
+notion ls --type database
+```
+
+| Flag | Description |
+|------|-------------|
+| `--sort <asc\|desc>` | Sort by last edited time |
+| `--type <page\|database>` | Filter by object type |
+| `--cursor <cursor>` | Pagination cursor from a previous `--next` hint |
+| `--json` | Force JSON output |
+
 ### `notion update <id|url>`
 
 Update properties on any Notion page (standalone or database entry).
@@ -120,3 +141,45 @@ notion update "$PAGE_ID" --prop "Status=Done" --json
 | `date` | `--prop "Due=2024-12-25"` or `--prop "Range=2024-01-01,2024-01-31"` |
 
 Required integration capabilities: **Read content**, **Update content**
+
+### `notion archive <id|url>`
+
+Archive (trash) a Notion page.
+
+```bash
+# Archive a page by ID
+notion archive "$PAGE_ID"
+
+# Archive a page by URL
+notion archive "https://www.notion.so/My-Page-b55c9c91384d452b81dbd1ef79372b75"
+
+# Output the full updated page object as JSON
+notion archive "$PAGE_ID" --json
+```
+
+Required integration capabilities: **Read content**, **Update content**
+
+### `notion comment [id|url] -m <text>`
+
+Add a comment to a page, block, or discussion thread.
+
+```bash
+# Page-level comment
+notion comment "$PAGE_ID" -m "Reviewed and approved."
+
+# Reply to an existing discussion thread (use discussion ID from `notion comments`)
+notion comment --reply-to "$DISCUSSION_ID" -m "Agreed, let's proceed."
+
+# Comment on a specific block
+notion comment --block "$BLOCK_ID" -m "This section needs revision."
+```
+
+| Flag | Description |
+|------|-------------|
+| `-m, --message <text>` | Comment text (required) |
+| `--reply-to <discussion-id>` | Reply to an existing discussion thread |
+| `--block <block-id>` | Comment on a specific block |
+
+The `notion comments <id>` list command now shows `DISCUSSION` and `PARENT` columns so agents can reference discussion IDs with `--reply-to`.
+
+Required integration capabilities: **Read content**, **Insert content**, **Read comments**, **Insert comments**

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

@@ -24,7 +24,8 @@ Pages must be shared with your integration: open page → `⋯` → **Add connec
 
 **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`: also need **Insert content**
+- `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 comment`: also need **Read comments** + **Insert comments**
 
@@ -109,14 +110,38 @@ notion db query <id|url> --json | jq '.[] | .properties'
 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 create-page --parent <id|url> --title "Title"               # title-only page
-notion create-page --parent <id|url> --title "Title" -m "# Hello"  # with markdown body
-echo "# Content" | notion create-page --parent <id|url> --title "Title"  # from stdin
+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
+
+# 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
+notion create-page --parent <id|url> --title "Page" --icon "🚀"
+notion create-page --parent <id|url> --title "Page" --cover "https://example.com/img.jpg"
+
 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
 ```
 
+#### 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.
+
 #### Surgical Editing
 
 Search-and-replace specific text, replace the full page, or insert content at a specific location.
@@ -197,6 +222,12 @@ 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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrzejchm/notion-cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Read Notion pages and databases from the terminal. Built for AI agents and developers.",
   "keywords": [
     "notion",