@andrzejchm/notion-cli 0.8.0 → 0.9.1

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.8.0)
+- **CLI** = `@andrzejchm/notion-cli` (this repo, v0.9.0)
 - **MCP** = Official Notion MCP server
 
 ---
@@ -13,18 +13,18 @@
 
 | 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 edit | Multi-op `--find`/`--replace`, `--range` | Search-and-replace (multi-op), full replace, template apply, verification | Partial |
 | 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 | `archive` | Trash pages | ✅ Parity |
-| Database create | - | SQL DDL `CREATE TABLE` syntax | Gap |
+| 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 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 | `create-page --parent <db>` with `--prop` | Full property support, date/place/checkbox expanded formats | ✅ Parity |
@@ -56,25 +56,23 @@ These gaps directly limit what an AI agent can accomplish through the CLI compar
 **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
+#### 6. ✅ Create databases (shipped v0.10.0)
 **MCP:** `CREATE TABLE` DDL with full type system (select, relation, rollup, formula, unique_id, etc.).
-**CLI:** No equivalent.
-**Why:** Agents building project scaffolds or workflows need to create structured databases, not just pages.
-**Suggested command:** `notion create-db --parent <id> --title "Tasks" --schema "Name TITLE, Status SELECT(Todo,Done)"`
+**CLI:** `notion db create --parent <id> --title "Tasks" --prop "Status:select:To Do,Done"` — supports title, rich_text, number, select, multi_select, status, date, checkbox, url, email, phone_number, people, files, created_time, last_edited_time. Relation, rollup, formula, and unique_id are not supported (too complex for CLI flags).
+**Status:** Shipped in v0.10.0.
 
 #### 7. Move pages
 **MCP:** Batch move up to 100 pages/databases to a new parent (page, database, data source, or workspace).
@@ -88,11 +86,10 @@ These gaps directly limit what an AI agent can accomplish through the CLI compar
 **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"`
 
-#### 9. Multi-operation content editing
+#### 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.
-**CLI:** `notion edit-page` supports single `--range` replacement. No batch search-and-replace.
-**Why:** Agents making multiple edits to a page (updating several sections) currently need multiple CLI invocations.
-**Suggested approach:** Support multiple `--replace "old...new"` flags or a JSON patch file.
+**CLI:** `notion edit-page` supports multiple `--find`/`--replace` pairs in a single invocation (PR #6).
+**Status:** Shipped in v0.9.0.
 
 #### 10. Duplicate pages
 **MCP:** `duplicate-page` — async copy of any accessible page.
@@ -181,6 +178,6 @@ The CLI isn't just chasing MCP parity — it has unique strengths:
 
 ---
 
-*Last updated: 2026-03-23*
-*CLI version compared: 0.8.0*
+*Last updated: 2026-03-24*
+*CLI version compared: 0.9.0*
 *MCP version compared: Official Notion MCP (2026-03)*

package/docs/README.agents.md

@@ -1,10 +1,10 @@
-# notion-cli for OpenCode
+# notion-cli for AI Coding Agents
 
-Complete guide for using notion-cli with [OpenCode](https://opencode.ai).
+Complete guide for using notion-cli with AI coding agents (Claude Code, OpenCode, Cursor, Windsurf, etc.).
 
 ## Quick Install
 
-Tell OpenCode:
+Tell your AI agent:
 
 ```
 Fetch and follow instructions from https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/README.agents.md
@@ -24,14 +24,17 @@ npm install -g @andrzejchm/notion-cli
 
 Homebrew bundles Node.js automatically. npm requires Node.js ≥ 22.
 
-### 2. Install the skill file
+### 2. Install the skill
 
-```bash
-mkdir -p ~/.config/opencode/skills/using-notion-cli
-curl -fsSL https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/skills/using-notion-cli/SKILL.md \
-  -o ~/.config/opencode/skills/using-notion-cli/SKILL.md
+The skill file teaches your AI agent how to use notion-cli. It follows the open [Agent Skills](https://agentskills.io) standard.
+
+**Skill URL:**
+```
+https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/skills/using-notion-cli/SKILL.md
 ```
 
+**Agent:** Ask the user whether they want the skill installed **globally** (all projects) or **per-project**, then consult your own documentation for the correct skill install path. The skill directory name must be `using-notion-cli` and the file must be named `SKILL.md`.
+
 ### 3. Authenticate
 
 **Interactive setup** (choose OAuth or integration token):
@@ -63,7 +66,7 @@ notion --version   # CLI installed
 notion ls          # auth works
 ```
 
-Restart OpenCode after installing. The skill is now discoverable via the `skill` tool.
+Restart your agent session after installing so it picks up the new skill.
 
 ## Updating
 
@@ -73,14 +76,33 @@ brew upgrade notion-cli
 
 # npm
 npm install -g @andrzejchm/notion-cli
-
-# Update skill file (either install method)
-curl -fsSL https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/skills/using-notion-cli/SKILL.md \
-  -o ~/.config/opencode/skills/using-notion-cli/SKILL.md
 ```
 
+To update the skill file, re-download it from the URL in step 2 to the same location.
+
 ## 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).
@@ -137,3 +159,28 @@ 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

@@ -1,8 +1,6 @@
 ---
 name: using-notion-cli
 description: Reads and writes Notion pages using the `notion` CLI tool. Use when accessing Notion content, searching workspace pages, querying database entries, reading page markdown, appending content, creating pages, or adding comments from the terminal or within automated workflows.
-license: MIT
-compatibility: opencode
 ---
 
 ## Setup

package/package.json

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