@andrzejchm/notion-cli 0.6.0 → 0.7.0

package/docs/FEATURE-PARITY.md

@@ -0,0 +1,189 @@
+# Feature Parity: notion-cli vs Notion MCP
+
+> Compared against the official Notion MCP server tools (2026-03).
+> This document tracks gaps and serves as a prioritized roadmap for closing them.
+
+**Legend:**
+- **CLI** = `@andrzejchm/notion-cli` (this repo, v0.6.0)
+- **MCP** = Official Notion MCP server
+
+---
+
+## Current Parity Summary
+
+| Area | CLI | MCP | Parity |
+|------|-----|-----|--------|
+| Search | Basic keyword | 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 |
+| Move pages | - | Batch move to any parent | Gap |
+| Duplicate pages | - | Duplicate with async content copy | Gap |
+| Archive/delete | - | Trash pages | Gap |
+| 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 |
+| 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 |
+| 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 |
+
+---
+
+## Prioritized Gaps (Roadmap)
+
+Ordered by impact for AI-agent workflows first, then developer productivity.
+
+### Tier 1 - High Impact (core agent workflows)
+
+These gaps directly limit what an AI agent can accomplish through the CLI compared to using MCP directly.
+
+#### 1. Update page properties
+**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"`
+
+#### 2. Create pages in databases (with properties)
+**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"`
+
+#### 3. Archive / trash pages
+**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>`
+
+#### 4. Search filters (date range, creator)
+**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`
+
+### Tier 2 - Medium Impact (power-user and advanced agent workflows)
+
+#### 5. Inline / anchored comments
+**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>`
+
+#### 6. Create databases
+**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)"`
+
+#### 7. Move pages
+**MCP:** Batch move up to 100 pages/databases to a new parent (page, database, data source, or workspace).
+**CLI:** No equivalent.
+**Why:** Reorganizing content (moving completed items to archive, restructuring projects) is a common agent task.
+**Suggested command:** `notion move <id...> --to <parent-id>`
+
+#### 8. Update database schema
+**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"`
+
+#### 9. Multi-operation content editing
+**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.
+
+#### 10. Duplicate pages
+**MCP:** `duplicate-page` — async copy of any accessible page.
+**CLI:** No equivalent.
+**Why:** Templating workflows — copy a template page to start a new project/sprint.
+**Suggested command:** `notion duplicate <id>`
+
+### Tier 3 - Lower Impact (nice-to-have, niche workflows)
+
+#### 11. 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
+**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
+**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)
+**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
+**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
+**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
+**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
+**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
+**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`
+
+---
+
+## What CLI Does That MCP Doesn't
+
+The CLI isn't just chasing MCP parity — it has unique strengths:
+
+| CLI Feature | MCP Equivalent |
+|---|---|
+| `notion open <id>` — open in browser | No equivalent |
+| `notion ls` — list all accessible content | Must use search with empty query |
+| `notion db schema` — human-readable schema | Must fetch database and parse response |
+| `notion auth` — multi-profile management with OAuth | N/A (MCP uses connection-level auth) |
+| `notion completion bash/zsh/fish` — shell completions | N/A |
+| `--verbose` — debug API requests | N/A |
+| Pipe-friendly output (stdin → page, table → stdout) | N/A (MCP is programmatic, not pipe-based) |
+| URL → ID normalization everywhere | Both support this |
+| `.notion.yaml` per-project config | N/A |
+
+---
+
+## Implementation Notes
+
+- 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
+- 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-23*
+*CLI version compared: 0.6.0*
+*MCP version compared: Official Notion MCP (2026-03)*

package/docs/README.agents.md

@@ -78,3 +78,45 @@ npm install -g @andrzejchm/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
 ```
+
+## Commands Reference
+
+### `notion update <id|url>`
+
+Update properties on any Notion page (standalone or database entry).
+
+```bash
+# Set a select property
+notion update "$PAGE_ID" --prop "Status=Done"
+
+# Set multiple properties at once
+notion update "$PAGE_ID" --prop "Status=In Progress" --prop "Priority=High"
+
+# Update the page title
+notion update "$PAGE_ID" --title "New Page Title"
+
+# Combine --title and --prop
+notion update "$PAGE_ID" --title "Updated" --prop "Status=Done"
+
+# Clear a property (set to empty)
+notion update "$PAGE_ID" --prop "Status="
+
+# Output the updated page as JSON
+notion update "$PAGE_ID" --prop "Status=Done" --json
+```
+
+**Supported property types:** `title`, `rich_text`, `select`, `status`, `multi_select`, `number`, `checkbox`, `url`, `email`, `phone_number`, `date`
+
+**`--prop` format details:**
+
+| Type | Example |
+|------|---------|
+| `title` / `rich_text` | `--prop "Name=My Title"` |
+| `select` / `status` | `--prop "Status=Done"` |
+| `multi_select` | `--prop "Tags=design,eng,qa"` |
+| `number` | `--prop "Count=42"` |
+| `checkbox` | `--prop "Done=true"` or `--prop "Done=yes"` |
+| `url` | `--prop "Link=https://example.com"` |
+| `date` | `--prop "Due=2024-12-25"` or `--prop "Range=2024-01-01,2024-01-31"` |
+
+Required integration capabilities: **Read content**, **Update content**

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

@@ -119,26 +119,32 @@ notion comment <id|url> -m "Reviewed and approved."      # add comment to a page
 
 #### Surgical Editing
 
-Insert content at a specific location or replace a targeted section instead of the whole page.
+Search-and-replace specific text, replace the full page, or insert content at a specific location.
 
 ```bash
-# Append after a matched section (inserts new blocks right after the match)
-notion append <id|url> -m "New content" --after "## Status...end of status"
+# Search-and-replace: find text and replace it
+notion edit-page <id|url> --find "old text" --replace "new text"
+
+# Multiple search-and-replace operations in one call
+notion edit-page <id|url> --find "old1" --replace "new1" --find "old2" --replace "new2"
+
+# Replace all occurrences (not just the first match)
+notion edit-page <id|url> --find "TODO" --replace "DONE" --all
 
 # Replace an entire page's content
 notion edit-page <id|url> -m "# Replacement\nNew full-page content"
 
-# Replace only a matched section (leaves the rest of the page intact)
-notion edit-page <id|url> -m "## Updated Section\nNew text" --range "## Old Section...old last line"
+# Pipe replacement content from a file
+cat updated-section.md | notion edit-page <id|url>
 
-# Replace a section that contains child pages/databases (requires explicit opt-in)
-notion edit-page <id|url> -m "## Clean Slate" --range "## Archive...end" --allow-deleting-content
+# Allow deletion of child pages/databases during replace
+notion edit-page <id|url> -m "## Clean Slate" --allow-deleting-content
 
-# Pipe replacement content from a file
-cat updated-section.md | notion edit-page <id|url> --range "## Notes...end of notes"
+# Append after a matched section (inserts new blocks right after the match)
+notion append <id|url> -m "New content" --after "## Status...end of status"
 ```
 
-> **Ellipsis selector format:** Both `--after` and `--range` use the same selector syntax: `"start text...end text"`. Provide ~10 characters from the beginning of the target content, three dots (`...`), then ~10 characters from the end. The selector matches the first contiguous range of blocks whose text starts with the prefix and ends with the suffix. Run `notion read <id>` first to see the exact content and pick accurate selectors.
+> **`--range` (deprecated):** The `--range` flag still works for backward compatibility but uses the older `replace_content_range` API. Prefer `--find`/`--replace` for targeted edits.
 
 ---
 
@@ -180,14 +186,16 @@ echo "Created: $URL"
 # Pipe command output into a new page
 my-report-command | notion create-page --parent "$PAGE_ID" --title "Auto Report"
 
-# Surgically update a specific section of a page
-# 1. Read the page to find the section boundaries
+# Surgically update specific text on a page
+# 1. Read the page to find the text you want to change
 notion read "$PAGE_ID"
-# 2. Identify a selector from the output, e.g. the section starts with "## Status"
-#    and ends with "Blocked: none" — build the ellipsis selector from those
-# 3. Replace just that section
-notion edit-page "$PAGE_ID" -m "## Status\nAll tasks complete.\nBlocked: none" \
-  --range "## Status...Blocked: none"
+# 2. Use --find/--replace to swap specific text
+notion edit-page "$PAGE_ID" --find "Status: In Progress" --replace "Status: Done"
+
+# Multiple replacements in one call
+notion edit-page "$PAGE_ID" \
+  --find "Status: In Progress" --replace "Status: Done" \
+  --find "Blocked: yes" --replace "Blocked: none"
 
 # Insert a new sub-section after an existing section
 notion append "$PAGE_ID" -m "## New Sub-section\nContent here" \
@@ -214,4 +222,6 @@ notion append "$PAGE_ID" -m "## New Sub-section\nContent here" \
 
 **`notion edit-page` returns "Insufficient permissions"** — Enable **Update content** in integration capabilities.
 
-**`--range` / `--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.
+**`--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.

package/docs/testing-setup.md

@@ -0,0 +1,250 @@
+# Integration Testing Setup
+
+This guide walks through setting up a Notion workspace for running integration tests against the `notion-cli` tool.
+
+## Prerequisites
+
+- A Notion account (free plan works)
+- Node.js >= 22
+- This repository cloned locally
+
+## 1. Create a Notion Integration
+
+1. Go to [https://www.notion.so/profile/integrations](https://www.notion.so/profile/integrations)
+2. Click **"New integration"**
+3. Name it `notion-cli-tests`
+4. Select the workspace you want to use for testing
+5. Under **Capabilities**, enable:
+   - **Read content**
+   - **Update content**
+   - **Insert content**
+   - **Read comments**
+   - **Create comments**
+6. Click **Save**
+7. Copy the **Internal Integration Token** (starts with `ntn_`) — you'll need it later
+
+## 2. Create Fixture Pages and Databases
+
+Create the following structure in your Notion workspace. All fixtures live under a single root page.
+
+### Root Page
+
+Create a page called **`notion-cli-test-fixtures`**. This is the parent for everything below.
+
+### Fixture Table
+
+| Fixture | Page/DB Name | Content |
+|---|---|---|
+| **Rich Content Page** | `Test: Rich Content` | See [Rich Content Page details](#rich-content-page) below |
+| **Simple Page** | `Test: Simple Page` | Title + a single paragraph: `"This is a simple test page with a single paragraph."` |
+| **Empty Page** | `Test: Empty Page` | Title only, no body content at all |
+| **Task Database** | `Test: Task Database` | See [Task Database details](#task-database) below |
+| **Empty Database** | `Test: Empty Database` | Same schema as Task Database, zero rows |
+| **Comments Page** | `Test: Comments Page` | See [Comments Page details](#comments-page) below |
+
+### Rich Content Page
+
+Create a page called `Test: Rich Content` with the following blocks (in order):
+
+1. **Heading 1**: `Main Heading`
+2. **Paragraph**: `This is a paragraph with **bold**, *italic*, and ~~strikethrough~~ text.`
+3. **Heading 2**: `Sub Heading`
+4. **Bulleted list** with 3 items:
+   - `First item`
+   - `Second item`
+   - `Third item`
+5. **Numbered list** with 3 items:
+   1. `Step one`
+   2. `Step two`
+   3. `Step three`
+6. **Toggle block**: Summary `Click to expand`, content `Hidden content inside toggle`
+7. **Callout block**: `This is an important callout` (use any emoji icon)
+8. **Code block** (language: `javascript`):
+   ```javascript
+   function hello() {
+     return "world";
+   }
+   ```
+9. **Table**: 3 columns × 2 data rows
+
+   | Name | Value | Notes |
+   |------|-------|-------|
+   | Alpha | 1 | First entry |
+   | Beta | 2 | Second entry |
+
+10. **Child page**: `Nested Child Page` — with a single paragraph: `"Content inside nested page."`
+
+### Task Database
+
+Create an inline database called `Test: Task Database` with these properties:
+
+| Property | Type | Configuration |
+|---|---|---|
+| **Title** | Title | (default title column) |
+| **Status** | Select | Options: `Not Started`, `In Progress`, `Done` |
+| **Priority** | Number | Number format: Number |
+| **Due Date** | Date | — |
+| **Tags** | Multi-select | Options: `bug`, `feature`, `docs`, `urgent` |
+
+Add 5–10 rows with varied data. Example rows:
+
+| Title | Status | Priority | Due Date | Tags |
+|---|---|---|---|---|
+| Fix login bug | In Progress | 1 | 2025-03-01 | bug, urgent |
+| Add search feature | Not Started | 2 | 2025-04-15 | feature |
+| Update README | Done | 3 | 2025-02-01 | docs |
+| Refactor auth module | In Progress | 1 | 2025-03-10 | feature |
+| Write API docs | Not Started | 2 | 2025-05-01 | docs |
+
+### Empty Database
+
+Create an inline database called `Test: Empty Database` with the **exact same schema** as the Task Database (Title, Status, Priority, Due Date, Tags) but **do not add any rows**.
+
+### Comments Page
+
+Create a page called `Test: Comments Page` with:
+
+- **Body**: A single paragraph: `"This page is used to test comment retrieval."`
+- **Page-level comments** (add 2–3 via the page comment area):
+  1. `"First test comment"`
+  2. `"Second test comment"`
+  3. `"Third test comment"` (optional)
+- **Inline comment**: Select the word `"comment"` in the paragraph and add a discussion comment: `"Inline comment on selected text"`
+
+## 3. Share the Root Page with the Integration
+
+1. Open the `notion-cli-test-fixtures` page in Notion
+2. Click **"Share"** (top right) or the **"···"** menu → **"Connections"**
+3. Search for `notion-cli-tests` and add it
+4. Confirm the integration has access — all child pages and databases inherit the connection
+
+## 4. Extract Page and Database IDs
+
+Each Notion page/database has a unique ID embedded in its URL.
+
+**From a page URL:**
+```
+https://www.notion.so/Your-Page-Title-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
+                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                                       This is the page ID (32 hex chars)
+```
+
+Format it as a UUID: `1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d`
+
+**From a database URL:**
+```
+https://www.notion.so/1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d?v=...
+                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                       This is the database ID
+```
+
+The 32-character hex string after the last `/` (and before any `?`) is the ID. You can use it with or without dashes.
+
+Open each fixture page/database and extract its ID.
+
+## 5. Configure `.env.test`
+
+Copy the example file and fill in real values:
+
+```bash
+cp .env.test.example .env.test
+```
+
+Edit `.env.test` with the IDs you extracted:
+
+```bash
+# Internal integration token (starts with ntn_)
+NOTION_TEST_TOKEN=ntn_your_real_token
+
+# Root page containing all fixtures
+NOTION_TEST_ROOT_PAGE_ID=<id-of-notion-cli-test-fixtures-page>
+
+# Rich Content Page
+NOTION_FIXTURE_RICH_PAGE_ID=<id-of-test-rich-content-page>
+
+# Simple Page
+NOTION_FIXTURE_SIMPLE_PAGE_ID=<id-of-test-simple-page>
+
+# Empty Page
+NOTION_FIXTURE_EMPTY_PAGE_ID=<id-of-test-empty-page>
+
+# Task Database
+NOTION_FIXTURE_TASK_DB_ID=<id-of-test-task-database>
+
+# Empty Database
+NOTION_FIXTURE_EMPTY_DB_ID=<id-of-test-empty-database>
+
+# Comments Page
+NOTION_FIXTURE_COMMENTS_PAGE_ID=<id-of-test-comments-page>
+```
+
+### Environment Variable Reference
+
+| Variable | Description |
+|---|---|
+| `NOTION_TEST_TOKEN` | Internal integration token from step 1. The test runner passes this as `NOTION_API_TOKEN` to the CLI (the env var the CLI reads for auth — see `src/config/token.ts`). |
+| `NOTION_TEST_ROOT_PAGE_ID` | ID of the `notion-cli-test-fixtures` root page. Used to verify integration access. |
+| `NOTION_FIXTURE_RICH_PAGE_ID` | ID of the `Test: Rich Content` page. Tests heading, list, toggle, callout, code block, table, and nested child page rendering. |
+| `NOTION_FIXTURE_SIMPLE_PAGE_ID` | ID of the `Test: Simple Page` page. Tests basic page read with title and a single paragraph. |
+| `NOTION_FIXTURE_EMPTY_PAGE_ID` | ID of the `Test: Empty Page` page. Tests reading a page with no body content. |
+| `NOTION_FIXTURE_TASK_DB_ID` | ID of the `Test: Task Database` database. Tests database queries, filtering, sorting across multiple property types. |
+| `NOTION_FIXTURE_EMPTY_DB_ID` | ID of the `Test: Empty Database` database. Tests querying a database that returns zero results. |
+| `NOTION_FIXTURE_COMMENTS_PAGE_ID` | ID of the `Test: Comments Page` page. Tests reading page-level and inline comments. |
+
+> **Important:** The CLI authenticates via the `NOTION_API_TOKEN` environment variable (not `NOTION_TOKEN`). Integration tests store the token as `NOTION_TEST_TOKEN` and the test runner helper is responsible for passing it as `NOTION_API_TOKEN` when spawning CLI processes.
+
+## 6. Install Optional Dependencies
+
+Install `dotenv-cli` to load `.env.test` when running tests locally:
+
+```bash
+npm install --save-dev dotenv-cli
+```
+
+This is already listed as a devDependency if you've run `npm install` after pulling this change.
+
+## 7. Run Integration Tests
+
+Run integration tests locally with the test environment loaded:
+
+```bash
+npx dotenv -e .env.test -- npm run test:integration
+```
+
+This command:
+1. Loads variables from `.env.test` into the environment
+2. Runs `vitest run --config vitest.config.integration.ts`
+3. Vitest picks up test files from `tests/integration/**/*.test.ts`
+
+### Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `Script "test:integration" not found` | Run `npm install` to refresh scripts |
+| `401 Unauthorized` from Notion API | Verify `NOTION_TEST_TOKEN` is correct and the integration is still active |
+| `404 Not Found` for a fixture | Verify the page/database ID is correct and the root page is shared with the integration |
+| Tests time out | Default timeout is 30s per test. Check your network connection. |
+| `NOTION_API_TOKEN` not set errors | Make sure you're using `npx dotenv -e .env.test --` before the npm command |
+
+## CI Configuration
+
+Integration tests run automatically on **pull requests** via the `integration` job in `.github/workflows/ci.yml`. They do not run on push events, so pushes to `main` are never blocked by integration test failures.
+
+The job depends on the `ci` job (typecheck, lint, unit tests) passing first, then builds the CLI and runs `npm run test:integration`.
+
+### Required GitHub Actions Secrets
+
+Configure these secrets in your repository under **Settings → Secrets and variables → Actions**:
+
+| Secret | Description |
+|---|---|
+| `NOTION_TEST_TOKEN` | Internal integration token (starts with `ntn_`) |
+| `NOTION_TEST_ROOT_PAGE_ID` | ID of the `notion-cli-test-fixtures` root page |
+| `NOTION_FIXTURE_RICH_PAGE_ID` | ID of the `Test: Rich Content` page |
+| `NOTION_FIXTURE_SIMPLE_PAGE_ID` | ID of the `Test: Simple Page` page |
+| `NOTION_FIXTURE_EMPTY_PAGE_ID` | ID of the `Test: Empty Page` page |
+| `NOTION_FIXTURE_TASK_DB_ID` | ID of the `Test: Task Database` database |
+| `NOTION_FIXTURE_EMPTY_DB_ID` | ID of the `Test: Empty Database` database |
+| `NOTION_FIXTURE_COMMENTS_PAGE_ID` | ID of the `Test: Comments Page` page |
+
+These are the same values from your `.env.test` file (see [section 5](#5-configure-envtest) above). Each secret maps to the corresponding environment variable that the test runner expects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrzejchm/notion-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Read Notion pages and databases from the terminal. Built for AI agents and developers.",
   "keywords": [
     "notion",
@@ -43,11 +43,12 @@
     "format:write": "biome format --write .",
     "check": "biome check .",
     "check:write": "biome check --write .",
-    "ci": "npm run typecheck && npm run check"
+    "ci": "npm run typecheck && npm run check",
+    "test:integration": "vitest run --config vitest.config.integration.ts"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
-    "@notionhq/client": "^5.11.1",
+    "@notionhq/client": "^5.14.0",
     "chalk": "^5.6.0",
     "commander": "^14.0.0",
     "yaml": "^2.8.0"
@@ -56,6 +57,7 @@
     "@biomejs/biome": "^2.4.4",
     "@commander-js/extra-typings": "^14.0.0",
     "@types/node": "^22",
+    "dotenv-cli": "^11.0.0",
     "tsup": "^8.5.0",
     "typescript": "~5.9.0",
     "vitest": "^4.0.0"