@jordancoin/notioncli 1.0.0 → 1.1.0

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 
-A powerful CLI for the Notion API — query databases, manage pages, and automate your workspace from the terminal.
+A powerful CLI for the Notion API — aliases, zero UUIDs, relations & rollups, and full block-level CRUD. Built for humans and AI agents.
 
 **No more copy-pasting UUIDs.** Set up aliases once, then just type `notion query tasks` or `notion add projects --prop "Name=Ship it"`.
 
@@ -34,6 +34,39 @@ Zero UUIDs. One command. You're ready to go.
 
 ---
 
+## What's New (v1.1)
+
+notioncli now understands Notion as a **graph**, not just a table.
+
+- 🔗 **Relations** — `get` resolves linked page titles automatically. New `notion relations` command for exploring connected pages.
+- 📊 **Rollups** — Numbers, dates, and arrays are parsed into readable values. No more raw JSON blobs.
+- 🧱 **Blocks CRUD** — Edit and delete blocks directly with `block-edit` and `block-delete`. Use `--ids` flag on `blocks` for precise targeting.
+
+---
+
+## Notion as a Graph
+
+Notion databases don't live in isolation — they're connected by relations and rollups. notioncli treats your workspace as a **graph of linked pages**:
+
+```
+$ notion get tasks --filter "Name=Ship v1.1"
+Properties:
+  Name: Ship v1.1
+  Status: Active
+  Project: Launch CLI        ← relation resolved to title
+  Task Count: 3              ← rollup parsed to number
+
+$ notion relations tasks --filter "Name=Ship v1.1"
+Project: 1 linked page
+id        │ title      │ url
+──────────┼────────────┼──────────────────────
+302903e2… │ Launch CLI │ https://notion.so/...
+```
+
+Relations resolve to human-readable titles. Rollups return real values. Blocks can be queried, edited, and deleted directly. This makes it possible to explore, automate, and reason about complex workspaces entirely from the CLI.
+
+---
+
 ## Setup
 
 ### 1. Create a Notion Integration
@@ -90,7 +123,7 @@ notion alias rename reading-list reads
 
 ### `notion query` — Query a Database
 
-The command you'll use most. Filter, sort, and browse your data:
+The command you'll use most. Filter, sort, and browse your data. Rollups are automatically parsed into numbers, dates, or arrays instead of raw JSON.
 
 ```
 $ notion query projects
@@ -107,12 +140,6 @@ With filters and sorting:
 
 ```
 $ notion query projects --filter Status=Active --sort Date:desc --limit 5
-Date       │ Name          │ Status │ Priority
-───────────┼───────────────┼────────┼─────────
-2026-02-09 │ Launch CLI    │ Active │ High
-2026-02-08 │ Write Docs    │ Active │ Medium
-
-2 results
 ```
 
 ### `notion add` — Add a Page
@@ -143,52 +170,70 @@ $ notion update workouts --filter "Name=LEGS #5" --prop "Notes=Great session"
 
 ### `notion delete` — Delete (Archive) a Page
 
-By page ID:
-```
-$ notion delete a1b2c3d4-5678-90ab-cdef-1234567890ab
-🗑️  Archived page: a1b2c3d4-...
-   (Restore it from the trash in Notion if needed)
-```
-
-By alias + filter:
 ```
 $ notion delete workouts --filter "Date=2026-02-09"
 🗑️  Archived page: a1b2c3d4-...
+   (Restore it from the trash in Notion if needed)
 ```
 
 ### `notion get` — View Page Details
 
-By page ID:
-```
-$ notion get a1b2c3d4-5678-90ab-cdef-1234567890ab
-```
+Relations are **automatically resolved** to linked page titles:
 
-By alias + filter:
 ```
-$ notion get workouts --filter "Name=LEGS #5"
+$ notion get tasks --filter "Name=Implement relations"
 Page: a1b2c3d4-5678-90ab-cdef-1234567890ab
-URL:  https://www.notion.so/New-Feature-a1b2c3d4...
+URL:  https://www.notion.so/...
 Created: 2026-02-10T14:30:00.000Z
 Updated: 2026-02-10T14:30:00.000Z
 
 Properties:
-  Name: New Feature
-  Status: Todo
-  Date: 2026-02-10
-  Priority: High
+  Name: Implement relations
+  Project: Build CLI              ← resolved title, not a UUID
+  Done: ✓
+```
+
+### `notion relations` — Explore Connections
+
+See what a page is linked to, with resolved titles and URLs:
+
+```
+$ notion relations tasks --filter "Name=Implement relations"
+Project: 1 linked page
+id        │ title     │ url
+──────────┼───────────┼──────────────────────
+302903e2… │ Build CLI │ https://notion.so/...
 ```
 
-### `notion blocks` — View Page Content
+### `notion blocks` — View & Edit Page Content
+
+View blocks with optional IDs for targeting:
 
-By page ID or alias + filter:
 ```
-$ notion blocks projects --filter "Name=Project Overview"
-# Project Overview
-This is the main project page.
-• First task
-• Second task
-☑ Completed item
-☐ Pending item
+$ notion blocks tasks --filter "Name=Ship v1.1" --ids
+[a1b2c3d4] # Project Overview
+[e5f67890] This is the main project page.
+[abcd1234] • First task
+[efgh5678] ☑ Completed item
+```
+
+In v1.1+, blocks are fully editable and deletable — not just readable:
+
+```
+$ notion block-edit a1b2c3d4-5678-90ab-cdef-1234567890ab "Updated heading text"
+✅ Updated heading_1 block: a1b2c3d4…
+
+$ notion block-delete a1b2c3d4-5678-90ab-cdef-1234567890ab
+🗑️  Deleted block: a1b2c3d4…
+```
+
+Use `notion blocks --ids` to list block IDs for precise edits.
+
+### `notion append` — Add Content to a Page
+
+```
+$ notion append tasks "Status update: phase 1 complete" --filter "Name=Ship feature"
+✅ Appended text block to page a1b2c3d4-...
 ```
 
 ### `notion dbs` — List All Databases
@@ -207,12 +252,19 @@ f9e8d7c6-b5a4-3210-fedc-ba0987654321 │ Reading List     │ https://...
 
 ```
 $ notion search "meeting"
-id                                   │ type        │ title          │ url
-─────────────────────────────────────┼─────────────┼────────────────┼──────────────
-a1b2c3d4-e5f6-7890-abcd-ef1234567890 │ page        │ Meeting Notes  │ https://...
-f9e8d7c6-b5a4-3210-fedc-ba0987654321 │ data_source │ Meetings DB    │ https://...
+```
 
-2 results
+### `notion users` / `notion user <id>` — Workspace Users
+
+```
+$ notion users
+```
+
+### `notion comments` / `notion comment` — Page Comments
+
+```
+$ notion comments tasks --filter "Name=Ship feature"
+$ notion comment tasks "Shipped! 🚀" --filter "Name=Ship feature"
 ```
 
 ### `notion alias` — Manage Aliases
@@ -220,17 +272,10 @@ f9e8d7c6-b5a4-3210-fedc-ba0987654321 │ data_source │ Meetings DB    │ http
 Aliases are created automatically by `notion init`, but you can manage them:
 
 ```bash
-# See your aliases
-notion alias list
-
-# Rename one
-notion alias rename project-tracker projects
-
-# Add one manually (auto-discovers the right IDs)
-notion alias add tasks a1b2c3d4-e5f6-7890-abcd-ef1234567890
-
-# Remove one
-notion alias remove tasks
+notion alias list                              # See all aliases
+notion alias rename project-tracker projects   # Rename one
+notion alias add tasks <database-id>           # Add manually
+notion alias remove tasks                      # Remove one
 ```
 
 ### `--json` — Raw JSON Output
@@ -239,12 +284,20 @@ Add `--json` to any command for the raw Notion API response:
 
 ```bash
 notion --json query projects --limit 1
-notion --json dbs
-notion --json get a1b2c3d4-...
+notion --json get tasks --filter "Name=Ship it"
 ```
 
 Great for piping into `jq` or other tools.
 
+### `--output` — Output Formats
+
+```bash
+notion query tasks --output csv     # CSV
+notion query tasks --output yaml    # YAML
+notion query tasks --output json    # JSON
+notion query tasks --output table   # Default
+```
+
 ---
 
 ## Use It With AI Agents
@@ -263,17 +316,20 @@ notion query tasks --filter Status=Todo --sort Priority:desc
 notion add tasks --prop "Name=Fix bug #42" --prop "Status=In Progress"
 notion update tasks --filter "Name=Fix bug #42" --prop "Status=Done"
 
-# View, comment, and append — all by alias + filter
-notion get tasks --filter "Name=Fix bug #42"
-notion comment tasks "Shipped! 🚀" --filter "Name=Fix bug #42"
+# Explore relations between databases
+notion relations tasks --filter "Name=Fix bug #42"
+
+# View and edit page content
+notion blocks tasks --filter "Name=Fix bug #42" --ids
+notion block-edit <block-id> "Updated content"
 notion append tasks "Deployed to production" --filter "Name=Fix bug #42"
 
+# Comment and collaborate
+notion comment tasks "Shipped! 🚀" --filter "Name=Fix bug #42"
+
 # Delete by alias + filter
 notion delete tasks --filter "Name=Fix bug #42"
 
-# Or use raw page IDs if you already have them
-notion update <page-id> --prop "Status=Done"
-
 # Get raw JSON for parsing
 notion --json query projects --limit 10
 ```
@@ -282,7 +338,7 @@ No API key management, no curl commands, no JSON formatting — just simple shel
 
 ### Zero-UUID Workflow
 
-Every page-targeted command (`update`, `delete`, `get`, `blocks`, `comments`, `comment`, `append`) now accepts a **database alias + `--filter`** as an alternative to a raw page ID:
+Every page-targeted command (`update`, `delete`, `get`, `blocks`, `relations`, `comments`, `comment`, `append`, `block-edit`, `block-delete`) accepts a **database alias + `--filter`** as an alternative to a raw page ID:
 
 ```bash
 # Instead of: notion update a1b2c3d4-5678-90ab-cdef-1234567890ab --prop "Status=Done"
@@ -324,6 +380,12 @@ The latest Notion API introduced a dual-ID system for databases. Each database n
 
 You don't need to think about this. It just works.
 
+### Reliability
+
+- 139 unit tests
+- Tested against live Notion workspaces
+- Designed to fail loudly and safely when filters match zero or multiple pages
+
 ### Built on the Official SDK
 
 notioncli uses [`@notionhq/client`](https://github.com/makenotion/notion-sdk-js) v5.x, Notion's official JavaScript SDK.

package/bin/notion.js

@@ -203,7 +203,7 @@ async function buildFilter(dbIds, filterStr) {
 program
   .name('notion')
   .description('A powerful CLI for the Notion API — query databases, manage pages, and automate your workspace from the terminal.')
-  .version('1.0.0')
+  .version('1.1.0')
   .option('--json', 'Output raw JSON instead of formatted tables');
 
 // ─── init ──────────────────────────────────────────────────────────────────────
@@ -619,7 +619,43 @@ program
       console.log('');
       console.log('Properties:');
       for (const [name, prop] of Object.entries(page.properties)) {
-        console.log(`  ${name}: ${propValue(prop)}`);
+        if (prop.type === 'relation') {
+          const rels = prop.relation || [];
+          if (rels.length === 0) {
+            console.log(`  ${name}: (none)`);
+          } else {
+            // Resolve relation titles
+            const titles = [];
+            for (const rel of rels) {
+              try {
+                const linked = await notion.pages.retrieve({ page_id: rel.id });
+                let t = '';
+                for (const [, p] of Object.entries(linked.properties)) {
+                  if (p.type === 'title') { t = propValue(p); break; }
+                }
+                titles.push(t || rel.id.slice(0, 8) + '…');
+              } catch {
+                titles.push(rel.id.slice(0, 8) + '…');
+              }
+            }
+            console.log(`  ${name}: ${titles.join(', ')}`);
+          }
+        } else if (prop.type === 'rollup') {
+          const r = prop.rollup;
+          if (!r) {
+            console.log(`  ${name}: (empty)`);
+          } else if (r.type === 'number') {
+            console.log(`  ${name}: ${r.number != null ? r.number : '(empty)'}`);
+          } else if (r.type === 'date') {
+            console.log(`  ${name}: ${r.date ? r.date.start : '(empty)'}`);
+          } else if (r.type === 'array' && r.array) {
+            console.log(`  ${name}: ${r.array.map(item => propValue(item)).join(', ')}`);
+          } else {
+            console.log(`  ${name}: ${JSON.stringify(r)}`);
+          }
+        } else {
+          console.log(`  ${name}: ${propValue(prop)}`);
+        }
       }
     } catch (err) {
       console.error('Get failed:', err.message);
@@ -632,6 +668,7 @@ program
   .command('blocks <page-or-alias>')
   .description('Get page content as rendered blocks by ID or alias + filter')
   .option('--filter <key=value>', 'Filter to find the page (required when using an alias)')
+  .option('--ids', 'Show block IDs alongside content (for editing/deleting)')
   .action(async (target, opts, cmd) => {
     try {
       const notion = getNotion();
@@ -663,7 +700,8 @@ program
           : type === 'code' ? '```\n'
           : '';
         const suffix = type === 'code' ? '\n```' : '';
-        console.log(`${prefix}${text}${suffix}`);
+        const idTag = opts.ids ? `[${block.id.slice(0, 8)}] ` : '';
+        console.log(`${idTag}${prefix}${text}${suffix}`);
       }
     } catch (err) {
       console.error('Blocks failed:', err.message);
@@ -671,6 +709,165 @@ program
     }
   });
 
+// ─── block-edit ────────────────────────────────────────────────────────────────
+program
+  .command('block-edit <block-id> <text>')
+  .description('Update a block\'s text content')
+  .action(async (blockId, text, opts, cmd) => {
+    try {
+      const notion = getNotion();
+      // First retrieve the block to know its type
+      const block = await notion.blocks.retrieve({ block_id: blockId });
+      const type = block.type;
+
+      // Build the update payload based on block type
+      const supportedTextTypes = [
+        'paragraph', 'heading_1', 'heading_2', 'heading_3',
+        'bulleted_list_item', 'numbered_list_item', 'quote', 'callout', 'toggle',
+      ];
+
+      if (type === 'to_do') {
+        const res = await notion.blocks.update({
+          block_id: blockId,
+          to_do: {
+            rich_text: [{ text: { content: text } }],
+            checked: block.to_do?.checked || false,
+          },
+        });
+        if (getGlobalJson(cmd)) { console.log(JSON.stringify(res, null, 2)); return; }
+        console.log(`✅ Updated ${type} block: ${blockId.slice(0, 8)}…`);
+      } else if (supportedTextTypes.includes(type)) {
+        const res = await notion.blocks.update({
+          block_id: blockId,
+          [type]: {
+            rich_text: [{ text: { content: text } }],
+          },
+        });
+        if (getGlobalJson(cmd)) { console.log(JSON.stringify(res, null, 2)); return; }
+        console.log(`✅ Updated ${type} block: ${blockId.slice(0, 8)}…`);
+      } else if (type === 'code') {
+        const res = await notion.blocks.update({
+          block_id: blockId,
+          code: {
+            rich_text: [{ text: { content: text } }],
+            language: block.code?.language || 'plain text',
+          },
+        });
+        if (getGlobalJson(cmd)) { console.log(JSON.stringify(res, null, 2)); return; }
+        console.log(`✅ Updated code block: ${blockId.slice(0, 8)}…`);
+      } else {
+        console.error(`Block type "${type}" doesn't support text editing.`);
+        console.error('Supported types: paragraph, headings, lists, to_do, quote, callout, toggle, code');
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error('Block edit failed:', err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── block-delete ──────────────────────────────────────────────────────────────
+program
+  .command('block-delete <block-id>')
+  .description('Delete a block from a page')
+  .action(async (blockId, opts, cmd) => {
+    try {
+      const notion = getNotion();
+      const res = await notion.blocks.delete({ block_id: blockId });
+      if (getGlobalJson(cmd)) {
+        console.log(JSON.stringify(res, null, 2));
+        return;
+      }
+      console.log(`🗑️  Deleted block: ${blockId.slice(0, 8)}…`);
+    } catch (err) {
+      console.error('Block delete failed:', err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── relations ─────────────────────────────────────────────────────────────────
+program
+  .command('relations <page-or-alias>')
+  .description('Show all relation and rollup properties with resolved titles')
+  .option('--filter <key=value>', 'Filter to find the page (required when using an alias)')
+  .action(async (target, opts, cmd) => {
+    try {
+      const notion = getNotion();
+      const { pageId } = await resolvePageId(target, opts.filter);
+      const page = await notion.pages.retrieve({ page_id: pageId });
+
+      if (getGlobalJson(cmd)) {
+        console.log(JSON.stringify(page, null, 2));
+        return;
+      }
+
+      let found = false;
+
+      for (const [name, prop] of Object.entries(page.properties)) {
+        if (prop.type === 'relation') {
+          const rels = prop.relation || [];
+          if (rels.length === 0) {
+            console.log(`\n${name}: (no linked pages)`);
+            continue;
+          }
+          found = true;
+          console.log(`\n${name}: ${rels.length} linked page${rels.length !== 1 ? 's' : ''}`);
+
+          // Resolve each related page title
+          const rows = [];
+          for (const rel of rels) {
+            try {
+              const linked = await notion.pages.retrieve({ page_id: rel.id });
+              let title = '';
+              for (const [, p] of Object.entries(linked.properties)) {
+                if (p.type === 'title') {
+                  title = propValue(p);
+                  break;
+                }
+              }
+              rows.push({
+                id: rel.id.slice(0, 8) + '…',
+                title: title || '(untitled)',
+                url: linked.url || '',
+              });
+            } catch {
+              rows.push({ id: rel.id.slice(0, 8) + '…', title: '(access denied)', url: '' });
+            }
+          }
+          printTable(rows, ['id', 'title', 'url']);
+        }
+
+        if (prop.type === 'rollup') {
+          found = true;
+          const r = prop.rollup;
+          console.log(`\n${name} (rollup):`);
+          if (!r) {
+            console.log('  (empty)');
+            continue;
+          }
+          if (r.type === 'number') {
+            console.log(`  ${r.function || 'value'}: ${r.number}`);
+          } else if (r.type === 'date') {
+            console.log(`  ${r.date ? r.date.start : '(empty)'}`);
+          } else if (r.type === 'array' && r.array) {
+            for (const item of r.array) {
+              console.log(`  • ${propValue(item)}`);
+            }
+          } else {
+            console.log(`  ${JSON.stringify(r)}`);
+          }
+        }
+      }
+
+      if (!found) {
+        console.log('This page has no relation or rollup properties.');
+      }
+    } catch (err) {
+      console.error('Relations failed:', err.message);
+      process.exit(1);
+    }
+  });
+
 // ─── dbs ───────────────────────────────────────────────────────────────────────
 program
   .command('dbs')

package/lib/helpers.js

@@ -74,10 +74,25 @@ function propValue(prop) {
         return f.string || f.number?.toString() || f.boolean?.toString() || f.date?.start || '';
       }
       return '';
-    case 'relation':
-      return (prop.relation || []).map(r => r.id).join(', ');
-    case 'rollup':
-      return JSON.stringify(prop.rollup);
+    case 'relation': {
+      const rels = prop.relation || [];
+      if (rels.length === 0) return '';
+      if (rels.length === 1) return `→ ${rels[0].id.slice(0, 8)}…`;
+      return `→ ${rels.length} linked`;
+    }
+    case 'rollup': {
+      const r = prop.rollup;
+      if (!r) return '';
+      switch (r.type) {
+        case 'number': return r.number != null ? String(r.number) : '';
+        case 'date': return r.date ? (r.date.end ? `${r.date.start} → ${r.date.end}` : r.date.start) : '';
+        case 'array': {
+          if (!r.array || r.array.length === 0) return '';
+          return r.array.map(item => propValue(item)).join(', ');
+        }
+        default: return JSON.stringify(r);
+      }
+    }
     case 'people':
       return (prop.people || []).map(p => p.name || p.id).join(', ');
     case 'files':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jordancoin/notioncli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A powerful CLI for the Notion API — query databases, manage pages, and automate your workspace from the terminal.",
   "main": "bin/notion.js",
   "bin": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notion
-description: Notion API for creating and managing pages, databases, and blocks via the notioncli CLI tool.
+description: Notion API for creating and managing pages, databases, blocks, relations, and rollups via the notioncli CLI tool.
 homepage: https://github.com/JordanCoin/notioncli
 metadata:
   openclaw:
@@ -8,7 +8,7 @@ metadata:
     requires:
       env: ["NOTION_API_KEY"]
     primaryEnv: NOTION_API_KEY
-    install: "npm install -g notioncli"
+    install: "npm install -g @jordancoin/notioncli"
 ---
 
 # notioncli — Notion API Skill
@@ -120,6 +120,27 @@ notion delete tasks --filter "Name=Old task"         # By alias + filter
 notion delete workouts --filter "Date=2026-02-09"    # By alias + filter
 ```
 
+### Relations & Rollups
+
+```bash
+notion relations tasks --filter "Name=Ship feature"           # See linked pages with titles
+notion relations projects --filter "Name=Launch CLI"          # Explore connections
+```
+
+Relations are automatically resolved to page titles in `get` output. Rollups are parsed into numbers, dates, or arrays instead of raw JSON.
+
+### Blocks CRUD
+
+```bash
+notion blocks tasks --filter "Name=Ship feature"              # View page content
+notion blocks tasks --filter "Name=Ship feature" --ids        # View with block IDs
+notion append tasks "New paragraph" --filter "Name=Ship feature"  # Append block
+notion block-edit <block-id> "Updated text"                   # Edit a block
+notion block-delete <block-id>                                # Delete a block
+```
+
+Use `--ids` to get block IDs, then target specific blocks with `block-edit` or `block-delete`.
+
 ### Appending Content
 
 ```bash

package/skill/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "id": "notioncli",
+  "name": "notioncli — Notion CLI",
+  "description": "Query databases, manage pages, explore relations, and edit blocks in your Notion workspace from the terminal.",
+  "longDescription": "A powerful CLI for the Notion API built for both humans and AI agents. Auto-discovers databases and creates aliases so you never type UUIDs. Supports querying, filtering, sorting, creating, updating, deleting pages, comments, and appending content. Works with Notion's 2025 dual-ID API. Zero-UUID workflow via alias + filter on every command.",
+  "category": "Productivity",
+  "price": 0,
+  "icon": "📝",
+  "author": "JordanCoin",
+  "authorUrl": "https://github.com/JordanCoin",
+  "repository": "https://github.com/JordanCoin/notioncli",
+  "version": "1.1.0",
+  "tags": ["notion", "cli", "api", "database", "productivity", "workspace", "automation", "ai-agent"],
+  "requirements": ["Node.js >= 18", "Notion API key (free)"],
+  "optional": []
+}

package/test/debug-parent.js

@@ -0,0 +1,32 @@
+const { Client } = require('@notionhq/client');
+const h = require('../lib/helpers');
+const notion = new Client({ auth: h.loadConfig(h.getConfigPaths().CONFIG_PATH).apiKey });
+const parentId = '302903e2-cff4-8059-b808-e3c953fd7d26';
+
+(async () => {
+  const db = await notion.databases.create({
+    parent: { type: 'page_id', page_id: parentId },
+    title: [{ text: { content: 'Quick Test DB' } }],
+    properties: { Name: { title: {} }, Priority: { number: {} } }
+  });
+  console.log('DB created:', db.id.slice(0,8));
+  console.log('DB keys with id:', Object.keys(db).filter(k => k.includes('id')));
+  console.log('database_id:', db.database_id);
+
+  await new Promise(r => setTimeout(r, 2000));
+
+  for (const pt of ['data_source_id', 'database_id']) {
+    const pid = pt === 'database_id' && db.database_id ? db.database_id : db.id;
+    try {
+      const page = await notion.pages.create({
+        parent: { type: pt, [pt]: pid },
+        properties: { Name: { title: [{ text: { content: 'test ' + pt } }] } }
+      });
+      console.log(pt, 'WORKS:', page.id.slice(0,8));
+      await notion.pages.update({ page_id: page.id, archived: true });
+    } catch(e) { console.log(pt, 'FAILED:', e.code, e.message.slice(0,100)); }
+  }
+
+  await notion.blocks.delete({ block_id: db.id });
+  console.log('cleaned');
+})();

package/test/live-relations-test.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+// Live integration test: Relations, Rollups & Blocks CRUD
+// Creates temp databases, links them, tests CLI output, cleans up.
+
+const { Client } = require('@notionhq/client');
+const { execSync } = require('child_process');
+const path = require('path');
+
+const CLI = path.join(__dirname, '..', 'bin', 'notion.js');
+const run = (cmd) => execSync(`node ${CLI} ${cmd}`, { encoding: 'utf-8' }).trim();
+const runJson = (cmd) => JSON.parse(execSync(`node ${CLI} --json ${cmd}`, { encoding: 'utf-8' }));
+
+const notion = new Client({ auth: process.env.NOTION_API_KEY || require('../lib/helpers').loadConfig(
+  require('../lib/helpers').getConfigPaths().CONFIG_PATH
+).apiKey });
+
+let parentPageId = null;
+let projectsDbId = null;
+let projectsDsId = null;
+let tasksDbId = null;
+let tasksDsId = null;
+let testPageIds = [];
+let createdDbIds = [];
+
+async function setup() {
+  console.log('\n🔧 Setting up test databases...\n');
+
+  // Create a dedicated test page as parent (needs to be under a page the integration can access)
+  // First, find an existing page the integration has access to
+  const search = await notion.search({ filter: { value: 'page', property: 'object' }, page_size: 20 });
+  
+  // Look for a top-level page (parent is workspace), or any page that's not inside a database
+  let rootPageId = null;
+  for (const p of search.results) {
+    if (p.parent?.type === 'workspace' || p.parent?.type === 'page_id') {
+      rootPageId = p.id;
+      break;
+    }
+  }
+
+  if (!rootPageId) {
+    // No standalone page found — create the DBs using the workspace parent directly
+    // by creating a page in the integration's space
+    console.log('No standalone page found. Will use first available page.');
+    rootPageId = search.results[0]?.id;
+    if (!rootPageId) throw new Error('No pages accessible by integration');
+  }
+
+  // Create a test container page
+  const containerPage = await notion.pages.create({
+    parent: { type: 'page_id', page_id: rootPageId },
+    properties: {
+      title: { title: [{ text: { content: 'CLI Test Container (auto-delete)' } }] },
+    },
+  });
+  parentPageId = containerPage.id;
+  testPageIds.push(parentPageId);
+  console.log(`📄 Created test container page: ${parentPageId.slice(0, 8)}…`);
+
+  // 1. Create "CLI Test Projects" database
+  console.log('\nCreating Projects DB...');
+  const projectsDb = await notion.databases.create({
+    parent: { type: 'page_id', page_id: parentPageId },
+    title: [{ text: { content: 'CLI Test Projects' } }],
+    properties: {
+      'Name': { title: {} },
+      'Status': { select: { options: [
+        { name: 'Active', color: 'green' },
+        { name: 'Done', color: 'gray' },
+      ]}},
+      'Priority': { number: {} },
+    },
+  });
+  // databases.create() returns: .id = data_source_id, .database_id = database_id for page creation
+  projectsDsId = projectsDb.id;
+  projectsDbId = projectsDb.database_id || projectsDb.id;
+  createdDbIds.push(projectsDb.id);
+  console.log(`✅ Projects DB (db: ${projectsDbId.slice(0, 8)}…, ds: ${projectsDsId.slice(0, 8)}…)`);
+
+  // 2. Create "CLI Test Tasks" database with relation to Projects
+  console.log('Creating Tasks DB with relation...');
+  const tasksDb = await notion.databases.create({
+    parent: { type: 'page_id', page_id: parentPageId },
+    title: [{ text: { content: 'CLI Test Tasks' } }],
+    properties: {
+      'Name': { title: {} },
+      'Done': { checkbox: {} },
+      'Project': { relation: { database_id: projectsDbId } },
+    },
+  });
+  tasksDsId = tasksDb.id;
+  tasksDbId = tasksDb.database_id || tasksDb.id;
+  createdDbIds.push(tasksDb.id);
+  console.log(`✅ Tasks DB (db: ${tasksDbId.slice(0, 8)}…, ds: ${tasksDsId.slice(0, 8)}…)`);
+
+  // 3. Add project pages
+  console.log('\nAdding test data...');
+  const proj1 = await notion.pages.create({
+    parent: { type: 'database_id', database_id: projectsDbId },
+    properties: {
+      'Name': { title: [{ text: { content: 'Build CLI' } }] },
+      'Status': { select: { name: 'Active' } },
+      'Priority': { number: 1 },
+    },
+  });
+  testPageIds.push(proj1.id);
+  console.log(`  📌 Project: "Build CLI"`);
+
+  const proj2 = await notion.pages.create({
+    parent: { type: 'database_id', database_id: projectsDbId },
+    properties: {
+      'Name': { title: [{ text: { content: 'Write Docs' } }] },
+      'Status': { select: { name: 'Done' } },
+      'Priority': { number: 2 },
+    },
+  });
+  testPageIds.push(proj2.id);
+  console.log(`  📌 Project: "Write Docs"`);
+
+  // 4. Add task pages linked to projects
+  const task1 = await notion.pages.create({
+    parent: { type: 'database_id', database_id: tasksDbId },
+    properties: {
+      'Name': { title: [{ text: { content: 'Implement relations' } }] },
+      'Done': { checkbox: true },
+      'Project': { relation: [{ id: proj1.id }] },
+    },
+  });
+  testPageIds.push(task1.id);
+  console.log(`  📋 Task: "Implement relations" → Build CLI`);
+
+  const task2 = await notion.pages.create({
+    parent: { type: 'database_id', database_id: tasksDbId },
+    properties: {
+      'Name': { title: [{ text: { content: 'Add tests' } }] },
+      'Done': { checkbox: false },
+      'Project': { relation: [{ id: proj1.id }] },
+    },
+  });
+  testPageIds.push(task2.id);
+  console.log(`  📋 Task: "Add tests" → Build CLI`);
+
+  const task3 = await notion.pages.create({
+    parent: { type: 'database_id', database_id: tasksDbId },
+    properties: {
+      'Name': { title: [{ text: { content: 'Write README' } }] },
+      'Done': { checkbox: true },
+      'Project': { relation: [{ id: proj2.id }] },
+    },
+  });
+  testPageIds.push(task3.id);
+  console.log(`  📋 Task: "Write README" → Write Docs`);
+
+  // 5. Register CLI aliases
+  run(`alias add test-projects ${projectsDsId}`);
+  run(`alias add test-tasks ${tasksDsId}`);
+  console.log(`\n✅ Aliases registered: test-projects, test-tasks\n`);
+}
+
+async function runTests() {
+  let passed = 0;
+  let failed = 0;
+
+  function check(name, condition, detail) {
+    if (condition) {
+      console.log(`  ✅ ${name}`);
+      passed++;
+    } else {
+      console.log(`  ❌ ${name}${detail ? ' — ' + detail : ''}`);
+      failed++;
+    }
+  }
+
+  console.log('🧪 Running live tests...\n');
+
+  // --- Test 1: Query tasks — relation column formatting ---
+  console.log('--- 1. query (relation display) ---');
+  try {
+    const out = run('query test-tasks');
+    check('query shows tasks', out.includes('Implement relations'));
+    check('relation shows → format', out.includes('→'));
+    console.log(`\n${out.split('\n').map(l => '    ' + l).join('\n')}\n`);
+  } catch (e) { check('query test-tasks', false, e.message); }
+
+  // --- Test 2: Get task — resolve relation to project title ---
+  console.log('--- 2. get (relation resolution) ---');
+  try {
+    const out = run('get test-tasks --filter "Name=Implement relations"');
+    check('get resolves relation to title', out.includes('Build CLI'));
+    check('get shows URL', out.includes('notion.so'));
+    console.log(`\n${out.split('\n').map(l => '    ' + l).join('\n')}\n`);
+  } catch (e) { check('get with relation', false, e.message); }
+
+  // --- Test 3: Relations command — graph explorer ---
+  console.log('--- 3. relations (graph explorer) ---');
+  try {
+    const out = run('relations test-tasks --filter "Name=Implement relations"');
+    check('relations shows linked pages', out.includes('linked') || out.includes('Build CLI'));
+    console.log(`\n${out.split('\n').map(l => '    ' + l).join('\n')}\n`);
+  } catch (e) { check('relations command', false, e.message); }
+
+  // --- Test 4: Reverse relation (project → tasks) ---
+  console.log('--- 4. reverse relation ---');
+  try {
+    const out = run('relations test-projects --filter "Name=Build CLI"');
+    const hasLinks = out.includes('Implement') || out.includes('Add tests') || out.includes('linked');
+    check('project shows reverse relations', hasLinks);
+    console.log(`\n${out.split('\n').map(l => '    ' + l).join('\n')}\n`);
+  } catch (e) { check('reverse relation', false, e.message); }
+
+  // --- Test 5: Blocks --ids ---
+  console.log('--- 5. blocks --ids ---');
+  try {
+    run('append test-tasks "Test block for live test" --filter "Name=Implement relations"');
+    const out = run('blocks test-tasks --filter "Name=Implement relations" --ids');
+    check('blocks --ids shows ID prefix', out.includes('['));
+    check('blocks shows appended text', out.includes('Test block'));
+    console.log(`\n${out.split('\n').map(l => '    ' + l).join('\n')}\n`);
+  } catch (e) { check('blocks --ids', false, e.message); }
+
+  // --- Test 6: Block edit ---
+  console.log('--- 6. block-edit ---');
+  try {
+    const json = runJson('blocks test-tasks --filter "Name=Implement relations"');
+    const blockId = json.results[json.results.length - 1].id;
+    const out = run(`block-edit ${blockId} "EDITED by CLI test"`);
+    check('block-edit succeeds', out.includes('✅'));
+    const verify = run('blocks test-tasks --filter "Name=Implement relations"');
+    check('edited content visible', verify.includes('EDITED'));
+    console.log(`\n${verify.split('\n').map(l => '    ' + l).join('\n')}\n`);
+  } catch (e) { check('block-edit', false, e.message); }
+
+  // --- Test 7: Block delete ---
+  console.log('--- 7. block-delete ---');
+  try {
+    const json = runJson('blocks test-tasks --filter "Name=Implement relations"');
+    const blockId = json.results[json.results.length - 1].id;
+    const out = run(`block-delete ${blockId}`);
+    check('block-delete succeeds', out.includes('🗑'));
+    const verify = run('blocks test-tasks --filter "Name=Implement relations"');
+    check('deleted content gone', !verify.includes('EDITED'));
+  } catch (e) { check('block-delete', false, e.message); }
+
+  // --- Test 8: JSON output preserves relation data ---
+  console.log('--- 8. json output ---');
+  try {
+    const json = runJson('get test-tasks --filter "Name=Implement relations"');
+    check('json has properties', !!json.properties);
+    check('json has relation property', !!json.properties.Project);
+    check('relation type correct', json.properties.Project.type === 'relation');
+    check('relation has linked IDs', json.properties.Project.relation.length > 0);
+  } catch (e) { check('json output', false, e.message); }
+
+  // --- Test 9: Query projects with rollup-like display ---
+  console.log('--- 9. query projects ---');
+  try {
+    const out = run('query test-projects');
+    check('query shows projects', out.includes('Build CLI'));
+    check('query shows both projects', out.includes('Write Docs'));
+    console.log(`\n${out.split('\n').map(l => '    ' + l).join('\n')}\n`);
+  } catch (e) { check('query projects', false, e.message); }
+
+  console.log(`\n${'═'.repeat(50)}`);
+  console.log(`Results: ${passed} passed, ${failed} failed out of ${passed + failed}`);
+  console.log('═'.repeat(50));
+  
+  return failed;
+}
+
+async function cleanup() {
+  console.log('\n🧹 Cleaning up...');
+  
+  // Archive pages first (before their parent DBs get deleted)
+  for (const id of testPageIds.filter(id => !createdDbIds.includes(id))) {
+    try { await notion.pages.update({ page_id: id, archived: true }); } catch {}
+  }
+  
+  // Then delete DBs and container page
+  for (const id of createdDbIds) {
+    try { await notion.blocks.delete({ block_id: id }); } catch {}
+  }
+  
+  // Delete container page last
+  if (parentPageId) {
+    try { await notion.blocks.delete({ block_id: parentPageId }); } catch {}
+  }
+
+  try { run('alias remove test-projects'); } catch {}
+  try { run('alias remove test-tasks'); } catch {}
+  
+  console.log('✅ Cleaned up\n');
+}
+
+async function main() {
+  try {
+    await setup();
+    const failures = await runTests();
+    await cleanup();
+    process.exit(failures > 0 ? 1 : 0);
+  } catch (err) {
+    console.error('\n💥 Test crashed:', err.message);
+    if (err.body) console.error('API body:', JSON.stringify(err.body).slice(0, 500));
+    if (err.stack) console.error(err.stack);
+    await cleanup().catch(() => {});
+    process.exit(1);
+  }
+}
+
+main();

package/test/unit.test.js

@@ -151,15 +151,54 @@ describe('propValue', () => {
     assert.equal(propValue({ type: 'formula', formula: null }), '');
   });
 
-  it('handles relation type', () => {
-    const prop = { type: 'relation', relation: [{ id: 'abc' }, { id: 'def' }] };
-    assert.equal(propValue(prop), 'abc, def');
+  it('handles relation type — empty', () => {
     assert.equal(propValue({ type: 'relation', relation: [] }), '');
   });
 
-  it('handles rollup type', () => {
-    const rollupData = { type: 'number', number: 100 };
-    assert.equal(propValue({ type: 'rollup', rollup: rollupData }), JSON.stringify(rollupData));
+  it('handles relation type — single', () => {
+    const prop = { type: 'relation', relation: [{ id: 'abc12345-6789-0000-0000-000000000000' }] };
+    assert.equal(propValue(prop), '→ abc12345…');
+  });
+
+  it('handles relation type — multiple', () => {
+    const prop = { type: 'relation', relation: [{ id: 'aaa' }, { id: 'bbb' }, { id: 'ccc' }] };
+    assert.equal(propValue(prop), '→ 3 linked');
+  });
+
+  it('handles rollup type — number', () => {
+    assert.equal(propValue({ type: 'rollup', rollup: { type: 'number', number: 100 } }), '100');
+  });
+
+  it('handles rollup type — null number', () => {
+    assert.equal(propValue({ type: 'rollup', rollup: { type: 'number', number: null } }), '');
+  });
+
+  it('handles rollup type — date', () => {
+    assert.equal(propValue({ type: 'rollup', rollup: { type: 'date', date: { start: '2026-02-09' } } }), '2026-02-09');
+  });
+
+  it('handles rollup type — date range', () => {
+    assert.equal(propValue({ type: 'rollup', rollup: { type: 'date', date: { start: '2026-02-01', end: '2026-02-28' } } }), '2026-02-01 → 2026-02-28');
+  });
+
+  it('handles rollup type — array', () => {
+    const rollup = {
+      type: 'array',
+      array: [
+        { type: 'number', number: 1 },
+        { type: 'number', number: 2 },
+        { type: 'number', number: 3 },
+      ],
+    };
+    assert.equal(propValue({ type: 'rollup', rollup }), '1, 2, 3');
+  });
+
+  it('handles rollup type — empty array', () => {
+    assert.equal(propValue({ type: 'rollup', rollup: { type: 'array', array: [] } }), '');
+  });
+
+  it('handles rollup type — null', () => {
+    assert.equal(propValue({ type: 'rollup', rollup: null }), '');
   });
 
   it('handles people type', () => {