@andrzejchm/notion-cli 0.5.0 → 0.7.0

package/README.md

@@ -95,7 +95,10 @@ notion ls
 | `notion comments <id\|url>` | Read page comments |
 | `notion comment <id\|url> -m <text>` | Add a comment to a page |
 | `notion append <id\|url> -m <markdown>` | Append markdown blocks to a page |
+| `notion edit-page <id\|url> --find <old> --replace <new>` | Search-and-replace text on a page |
+| `notion edit-page <id\|url> -m <markdown>` | Replace entire page content |
 | `notion create-page --parent <id\|url> --title <title>` | Create a new page, prints URL |
+| `notion update <id\|url> --prop "Name=Value"` | Update properties on a page |
 | `notion completion bash\|zsh\|fish` | Install shell tab completion |
 
 ### `notion db query` flags
@@ -188,6 +191,7 @@ Write commands require additional capabilities — enable in your integration se
 |---------|----------------------|
 | `notion append` | Read content, Insert content |
 | `notion create-page` | Read content, Insert content |
+| `notion update` | Read content, Update content |
 | `notion comment` | Read content, Insert content, Read comments, Insert comments |
 
 ---
@@ -208,6 +212,12 @@ Write commands require additional capabilities — enable in your integration se
 
 ---
 
+## Roadmap & Feature Parity
+
+See [docs/FEATURE-PARITY.md](docs/FEATURE-PARITY.md) for a detailed comparison of this CLI's capabilities against the official Notion MCP server, with prioritized gaps and planned additions.
+
+---
+
 ## License
 
 MIT © [Andrzej Chmielewski](https://github.com/andrzejchm)

package/dist/cli.js

@@ -4,7 +4,7 @@
 import { readFileSync } from "fs";
 import { dirname, join as join3 } from "path";
 import { fileURLToPath } from "url";
-import { Command as Command21 } from "commander";
+import { Command as Command22 } from "commander";
 
 // src/commands/append.ts
 import { Command } from "commander";
@@ -444,6 +444,12 @@ function withErrorHandling(fn) {
   });
 }
 
+// src/errors/notion-errors.ts
+var SELECTOR_HINT = 'Use an ellipsis selector matching page content, e.g. "## Section...end of section". Run `notion read <id>` to see the page content.';
+function isNotionValidationError(error2) {
+  return typeof error2 === "object" && error2 !== null && "code" in error2 && error2.code === "validation_error";
+}
+
 // src/notion/client.ts
 import { APIErrorCode, Client, isNotionClientError } from "@notionhq/client";
 async function validateToken(token) {
@@ -557,19 +563,23 @@ async function addComment(client, pageId, text, options = {}) {
     ...options.asUser && { display_name: { type: "user" } }
   });
 }
-async function appendMarkdown(client, pageId, markdown) {
+async function appendMarkdown(client, pageId, markdown, options) {
   await client.pages.updateMarkdown({
     page_id: pageId,
     type: "insert_content",
-    insert_content: { content: markdown }
+    insert_content: {
+      content: markdown,
+      ...options?.after != null && { after: options.after }
+    }
   });
 }
 function countOccurrences(text, sub) {
+  if (!sub) return 0;
   let count = 0;
   let pos = text.indexOf(sub, 0);
   while (pos !== -1) {
     count++;
-    pos = text.indexOf(sub, pos + 1);
+    pos = text.indexOf(sub, pos + sub.length);
   }
   return count;
 }
@@ -588,10 +598,46 @@ function buildContentRange(content) {
   }
   return content;
 }
-async function replaceMarkdown(client, pageId, newMarkdown) {
+async function searchAndReplace(client, pageId, updates, options) {
+  await client.pages.updateMarkdown({
+    page_id: pageId,
+    type: "update_content",
+    update_content: {
+      content_updates: updates.map((u) => ({
+        old_str: u.oldStr,
+        new_str: u.newStr,
+        ...options?.replaceAll && { replace_all_matches: true }
+      })),
+      ...options?.allowDeletingContent && { allow_deleting_content: true }
+    }
+  });
+}
+async function replacePageContent(client, pageId, newContent, options) {
+  await client.pages.updateMarkdown({
+    page_id: pageId,
+    type: "replace_content",
+    replace_content: {
+      new_str: newContent,
+      ...options?.allowDeletingContent && { allow_deleting_content: true }
+    }
+  });
+}
+async function replaceMarkdown(client, pageId, newMarkdown, options) {
   const current = await client.pages.retrieveMarkdown({ page_id: pageId });
   const currentContent = current.markdown.trim();
+  if (current.truncated && !options?.range) {
+    throw new CliError(
+      ErrorCodes.API_ERROR,
+      "Page content is too large for full-page replace (markdown was truncated by the API).",
+      "Use --range to replace a specific section instead."
+    );
+  }
   if (!currentContent) {
+    if (options?.range) {
+      process.stderr.write(
+        "Warning: page is empty, --range ignored, content inserted as-is.\n"
+      );
+    }
     if (newMarkdown.trim()) {
       await client.pages.updateMarkdown({
         page_id: pageId,
@@ -601,13 +647,15 @@ async function replaceMarkdown(client, pageId, newMarkdown) {
     }
     return;
   }
+  const contentRange = options?.range ?? buildContentRange(currentContent);
+  const allowDeletingContent = options?.allowDeletingContent ?? options?.range == null;
   await client.pages.updateMarkdown({
     page_id: pageId,
     type: "replace_content_range",
     replace_content_range: {
       content: newMarkdown,
-      content_range: buildContentRange(currentContent),
-      allow_deleting_content: true
+      content_range: contentRange,
+      allow_deleting_content: allowDeletingContent
     }
   });
 }
@@ -621,10 +669,11 @@ async function createPage(client, parentId, title, markdown) {
     },
     ...markdown.trim() ? { markdown } : {}
   });
-  return response.url;
+  const url = "url" in response ? response.url : response.id;
+  return url;
 }
 
-// src/commands/append.ts
+// src/utils/stdin.ts
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -632,34 +681,58 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
+
+// src/commands/append.ts
 function appendCommand() {
   const cmd = new Command("append");
-  cmd.description("append markdown content to a Notion page").argument("<id/url>", "Notion page ID or URL").option("-m, --message <markdown>", "markdown content to append").action(
-    withErrorHandling(async (idOrUrl, opts) => {
-      const { token, source } = await resolveToken();
-      reportTokenSource(source);
-      const client = createNotionClient(token);
-      let markdown = "";
-      if (opts.message) {
-        markdown = opts.message;
-      } else if (!process.stdin.isTTY) {
-        markdown = await readStdin();
-      } else {
-        throw new CliError(
-          ErrorCodes.INVALID_ARG,
-          "No content to append.",
-          "Pass markdown via -m/--message or pipe it through stdin"
-        );
-      }
-      if (!markdown.trim()) {
-        process.stdout.write("Nothing to append.\n");
-        return;
+  cmd.description("append markdown content to a Notion page").argument("<id/url>", "Notion page ID or URL").option("-m, --message <markdown>", "markdown content to append").option(
+    "--after <selector>",
+    'insert after matched content \u2014 ellipsis selector, e.g. "## Section...end of section"'
+  ).action(
+    withErrorHandling(
+      async (idOrUrl, opts) => {
+        const { token, source } = await resolveToken();
+        reportTokenSource(source);
+        const client = createNotionClient(token);
+        let markdown = "";
+        if (opts.message) {
+          markdown = opts.message;
+        } else if (!process.stdin.isTTY) {
+          markdown = await readStdin();
+        } else {
+          throw new CliError(
+            ErrorCodes.INVALID_ARG,
+            "No content to append.",
+            "Pass markdown via -m/--message or pipe it through stdin"
+          );
+        }
+        if (!markdown.trim()) {
+          process.stdout.write("Nothing to append.\n");
+          return;
+        }
+        const pageId = parseNotionId(idOrUrl);
+        const uuid = toUuid(pageId);
+        try {
+          await appendMarkdown(
+            client,
+            uuid,
+            markdown,
+            opts.after ? { after: opts.after } : void 0
+          );
+        } catch (error2) {
+          if (opts.after && isNotionValidationError(error2)) {
+            throw new CliError(
+              ErrorCodes.INVALID_ARG,
+              `Selector not found: "${opts.after}". ${error2.message}`,
+              SELECTOR_HINT,
+              error2
+            );
+          }
+          throw error2;
+        }
+        process.stdout.write("Appended.\n");
       }
-      const pageId = parseNotionId(idOrUrl);
-      const uuid = toUuid(pageId);
-      await appendMarkdown(client, uuid, markdown);
-      process.stdout.write("Appended.\n");
-    })
+    )
   );
   return cmd;
 }
@@ -1379,13 +1452,6 @@ function completionCommand() {
 
 // src/commands/create-page.ts
 import { Command as Command8 } from "commander";
-async function readStdin2() {
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks).toString("utf-8");
-}
 function createPageCommand() {
   const cmd = new Command8("create-page");
   cmd.description("create a new Notion page under a parent page").requiredOption("--parent <id/url>", "parent page ID or URL").requiredOption("--title <title>", "page title").option(
@@ -1401,7 +1467,7 @@ function createPageCommand() {
         if (opts.message) {
           markdown = opts.message;
         } else if (!process.stdin.isTTY) {
-          markdown = await readStdin2();
+          markdown = await readStdin();
         }
         const parentUuid = toUuid(parseNotionId(opts.parent));
         const url = await createPage(
@@ -1695,47 +1761,101 @@ function dbSchemaCommand() {
 
 // src/commands/edit-page.ts
 import { Command as Command11 } from "commander";
-async function readStdin3() {
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks).toString("utf-8");
+function collect2(val, acc) {
+  acc.push(val);
+  return acc;
 }
 function editPageCommand() {
   const cmd = new Command11("edit-page");
   cmd.description(
-    "replace the entire content of a Notion page with new markdown"
+    "replace a Notion page's content \u2014 full page or a targeted section"
   ).argument("<id/url>", "Notion page ID or URL").option(
     "-m, --message <markdown>",
     "new markdown content for the page body"
+  ).option(
+    "--find <text>",
+    "text to find (repeatable, pair with --replace)",
+    collect2,
+    []
+  ).option(
+    "--replace <text>",
+    "replacement text (repeatable, pair with --find)",
+    collect2,
+    []
+  ).option("--all", "replace all matches of each --find pattern").option(
+    "--range <selector>",
+    '[deprecated] ellipsis selector to replace only a section, e.g. "## My Section...last line"'
+  ).option(
+    "--allow-deleting-content",
+    "allow deletion of child pages/databases"
   ).action(
     withErrorHandling(async (idOrUrl, opts) => {
       const { token, source } = await resolveToken();
       reportTokenSource(source);
       const client = createNotionClient(token);
+      const pageId = parseNotionId(idOrUrl);
+      const uuid = toUuid(pageId);
+      if (opts.find.length > 0) {
+        if (opts.find.length !== opts.replace.length) {
+          throw new CliError(
+            ErrorCodes.INVALID_ARG,
+            `Mismatched --find/--replace: got ${opts.find.length} --find and ${opts.replace.length} --replace flags.`,
+            "Provide the same number of --find and --replace flags, paired by position."
+          );
+        }
+        const updates = opts.find.map((oldStr, i) => ({
+          oldStr,
+          newStr: opts.replace[i]
+        }));
+        await searchAndReplace(client, uuid, updates, {
+          replaceAll: opts.all ?? false,
+          allowDeletingContent: opts.allowDeletingContent ?? false
+        });
+        process.stdout.write("Page content updated.\n");
+        return;
+      }
       let markdown = "";
       if (opts.message) {
         markdown = opts.message;
       } else if (!process.stdin.isTTY) {
-        markdown = await readStdin3();
+        markdown = await readStdin();
         if (!markdown.trim()) {
           throw new CliError(
             ErrorCodes.INVALID_ARG,
             "No content provided (stdin was empty).",
-            "Pass markdown via -m/--message or pipe non-empty content through stdin"
+            "Pass content via -m/--message for full replacement, --find/--replace for targeted edits, or pipe content through stdin"
           );
         }
       } else {
         throw new CliError(
           ErrorCodes.INVALID_ARG,
           "No content provided.",
-          "Pass markdown via -m/--message or pipe it through stdin"
+          "Pass content via -m/--message for full replacement, --find/--replace for targeted edits, or pipe content through stdin"
         );
       }
-      const pageId = parseNotionId(idOrUrl);
-      const uuid = toUuid(pageId);
-      await replaceMarkdown(client, uuid, markdown);
+      if (opts.range) {
+        try {
+          await replaceMarkdown(client, uuid, markdown, {
+            range: opts.range,
+            allowDeletingContent: opts.allowDeletingContent ?? false
+          });
+        } catch (error2) {
+          if (isNotionValidationError(error2)) {
+            throw new CliError(
+              ErrorCodes.INVALID_ARG,
+              `Selector not found: "${opts.range}". ${error2.message}`,
+              SELECTOR_HINT,
+              error2
+            );
+          }
+          throw error2;
+        }
+        process.stdout.write("Page content replaced.\n");
+        return;
+      }
+      await replacePageContent(client, uuid, markdown, {
+        allowDeletingContent: opts.allowDeletingContent ?? false
+      });
       process.stdout.write("Page content replaced.\n");
     })
   );
@@ -2268,8 +2388,183 @@ function searchCommand() {
   return cmd;
 }
 
-// src/commands/users.ts
+// src/commands/update.ts
 import { Command as Command20 } from "commander";
+
+// src/services/update.service.ts
+var UNSUPPORTED_TYPES = /* @__PURE__ */ new Set([
+  "relation",
+  "formula",
+  "rollup",
+  "created_time",
+  "created_by",
+  "last_edited_time",
+  "last_edited_by",
+  "files",
+  "unique_id",
+  "verification",
+  "button"
+]);
+function buildPropertyUpdate(propName, propType, value) {
+  if (UNSUPPORTED_TYPES.has(propType)) {
+    throw new CliError(
+      ErrorCodes.INVALID_ARG,
+      `Property "${propName}" has type "${propType}" which cannot be set via the CLI.`,
+      "Supported types: title, rich_text, select, status, multi_select, number, checkbox, url, email, phone_number, date"
+    );
+  }
+  if (value === "") {
+    return null;
+  }
+  switch (propType) {
+    case "title":
+      return { title: [{ type: "text", text: { content: value } }] };
+    case "rich_text":
+      return { rich_text: [{ type: "text", text: { content: value } }] };
+    case "select":
+      return { select: { name: value } };
+    case "status":
+      return { status: { name: value } };
+    case "multi_select":
+      return {
+        multi_select: value.split(",").map((v) => v.trim()).filter(Boolean).map((v) => ({ name: v }))
+      };
+    case "number": {
+      const n = Number(value);
+      if (Number.isNaN(n)) {
+        throw new CliError(
+          ErrorCodes.INVALID_ARG,
+          `Invalid number value "${value}" for property "${propName}".`,
+          'Provide a numeric value, e.g. --prop "Count=42"'
+        );
+      }
+      return { number: n };
+    }
+    case "checkbox": {
+      const lower = value.toLowerCase();
+      return { checkbox: lower === "true" || lower === "yes" };
+    }
+    case "url":
+      return { url: value };
+    case "email":
+      return { email: value };
+    case "phone_number":
+      return { phone_number: value };
+    case "date": {
+      const parts = value.split(",");
+      const start = parts[0].trim();
+      const end = parts[1]?.trim();
+      return { date: end ? { start, end } : { start } };
+    }
+    default:
+      throw new CliError(
+        ErrorCodes.INVALID_ARG,
+        `Property "${propName}" has unsupported type "${propType}".`,
+        "Supported types: title, rich_text, select, status, multi_select, number, checkbox, url, email, phone_number, date"
+      );
+  }
+}
+function buildPropertiesPayload(propStrings, page) {
+  const result = {};
+  for (const propString of propStrings) {
+    const eqIdx = propString.indexOf("=");
+    if (eqIdx === -1) {
+      throw new CliError(
+        ErrorCodes.INVALID_ARG,
+        `Invalid --prop value: "${propString}". Expected format: "PropertyName=Value".`,
+        'Example: --prop "Status=Done"'
+      );
+    }
+    const propName = propString.slice(0, eqIdx).trim();
+    const value = propString.slice(eqIdx + 1);
+    const schemaProp = page.properties[propName];
+    if (!schemaProp) {
+      const available = Object.keys(page.properties).join(", ");
+      throw new CliError(
+        ErrorCodes.INVALID_ARG,
+        `Property "${propName}" not found on this page.`,
+        `Available properties: ${available}`
+      );
+    }
+    const propType = schemaProp.type;
+    const payload = buildPropertyUpdate(propName, propType, value);
+    result[propName] = payload;
+  }
+  return result;
+}
+async function updatePageProperties(client, pageId, properties) {
+  const response = await client.pages.update({
+    page_id: pageId,
+    properties
+  });
+  return response;
+}
+
+// src/commands/update.ts
+function collectProps(val, acc) {
+  acc.push(val);
+  return acc;
+}
+function updateCommand() {
+  const cmd = new Command20("update");
+  cmd.description("update properties on a Notion page").argument("<id/url>", "Notion page ID or URL").option(
+    "--prop <property=value>",
+    "set a property value (repeatable)",
+    collectProps,
+    []
+  ).option("--title <title>", "set the page title").action(
+    withErrorHandling(async (idOrUrl, opts) => {
+      if (opts.title === void 0 && opts.prop.length === 0) {
+        throw new CliError(
+          ErrorCodes.INVALID_ARG,
+          "No properties to update.",
+          'Provide at least one --prop "Name=Value" or --title "New Title"'
+        );
+      }
+      const { token, source } = await resolveToken();
+      reportTokenSource(source);
+      const client = createNotionClient(token);
+      const id = parseNotionId(idOrUrl);
+      const uuid = toUuid(id);
+      const page = await client.pages.retrieve({
+        page_id: uuid
+      });
+      const properties = buildPropertiesPayload(opts.prop, page);
+      if (opts.title !== void 0) {
+        const titleEntry = Object.entries(page.properties).find(
+          ([, prop]) => prop.type === "title"
+        );
+        if (!titleEntry) {
+          throw new CliError(
+            ErrorCodes.INVALID_ARG,
+            "This page has no title property.",
+            "Use --prop to set properties by name instead"
+          );
+        }
+        const [titlePropName] = titleEntry;
+        properties[titlePropName] = {
+          title: [{ type: "text", text: { content: opts.title } }]
+        };
+      }
+      const updatedPage = await updatePageProperties(
+        client,
+        uuid,
+        properties
+      );
+      const mode = getOutputMode();
+      if (mode === "json") {
+        process.stdout.write(`${formatJSON(updatedPage)}
+`);
+      } else {
+        process.stdout.write("Page updated.\n");
+      }
+    })
+  );
+  return cmd;
+}
+
+// src/commands/users.ts
+import { Command as Command21 } from "commander";
 function getEmailOrWorkspace(user) {
   if (user.type === "person") {
     return user.person.email ?? "\u2014";
@@ -2281,7 +2576,7 @@ function getEmailOrWorkspace(user) {
   return "\u2014";
 }
 function usersCommand() {
-  const cmd = new Command20("users");
+  const cmd = new Command21("users");
   cmd.description("list all users in the workspace").option("--json", "output as JSON").action(
     withErrorHandling(async (opts) => {
       if (opts.json) setOutputMode("json");
@@ -2312,7 +2607,7 @@ var __dirname = dirname(__filename);
 var pkg = JSON.parse(
   readFileSync(join3(__dirname, "../package.json"), "utf-8")
 );
-var program = new Command21();
+var program = new Command22();
 program.name("notion").description("Notion CLI \u2014 read Notion pages and databases from the terminal").version(pkg.version);
 program.option("--verbose", "show API requests/responses").option("--color", "force color output").option("--json", "force JSON output (overrides TTY detection)").option("--md", "force markdown output for page content");
 program.configureOutput({
@@ -2333,7 +2628,7 @@ program.hook("preAction", (thisCommand) => {
     setOutputMode("md");
   }
 });
-var authCmd = new Command21("auth").description("manage Notion authentication");
+var authCmd = new Command22("auth").description("manage Notion authentication");
 authCmd.action(authDefaultAction(authCmd));
 authCmd.addCommand(loginCommand());
 authCmd.addCommand(logoutCommand());
@@ -2343,7 +2638,7 @@ authCmd.addCommand(profileUseCommand());
 authCmd.addCommand(profileRemoveCommand());
 program.addCommand(authCmd);
 program.addCommand(initCommand(), { hidden: true });
-var profileCmd = new Command21("profile").description(
+var profileCmd = new Command22("profile").description(
   "manage authentication profiles"
 );
 profileCmd.addCommand(profileListCommand());
@@ -2360,7 +2655,8 @@ program.addCommand(commentAddCommand());
 program.addCommand(appendCommand());
 program.addCommand(createPageCommand());
 program.addCommand(editPageCommand());
-var dbCmd = new Command21("db").description("Database operations");
+program.addCommand(updateCommand());
+var dbCmd = new Command22("db").description("Database operations");
 dbCmd.addCommand(dbSchemaCommand());
 dbCmd.addCommand(dbQueryCommand());
 program.addCommand(dbCmd);