@andrzejchm/notion-cli 0.8.0 → 0.9.0

package/docs/FEATURE-PARITY.md

@@ -13,7 +13,7 @@
 
 | 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 |
@@ -24,7 +24,7 @@
 | 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 | `create-page --parent <db>` with `--prop` | Full property support, date/place/checkbox expanded formats | ✅ Parity |
@@ -56,19 +56,18 @@ 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
 **MCP:** `CREATE TABLE` DDL with full type system (select, relation, rollup, formula, unique_id, etc.).

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).
@@ -137,3 +158,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/package.json

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