@andrzejchm/notion-cli 0.10.0 → 0.11.0

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

@@ -0,0 +1,286 @@
+---
+name: using-notion-cli
+description: Use when reading or writing Notion pages, searching a Notion workspace, querying or creating Notion databases, appending or editing page content, creating pages, updating page properties, moving pages, adding comments, or archiving pages — via the `notion` CLI tool in the terminal.
+---
+
+## Overview - skill version 0.11.0
+
+`notion` is a CLI tool for reading and writing Notion content from the terminal or agent workflows. Use it any time you need to interact with Notion: read pages, search, query databases, append or edit content, create pages, update properties, move pages, post comments, or archive pages.
+
+> **Version check:** Run `notion --version`. If your installed version is older than 0.11.0, update with `npm install -g @andrzejchm/notion-cli` and refresh this skill with `notion skill`.
+
+## Setup
+
+Install once:
+
+```bash
+npm install -g @andrzejchm/notion-cli
+notion auth login   # interactive setup — choose OAuth or integration token
+```
+
+Or set env var (preferred for CI/agents):
+
+```bash
+export NOTION_API_TOKEN=ntn_your_token_here
+```
+
+Get token: https://www.notion.so/profile/integrations/internal
+
+Pages must be shared with your integration: open page → `⋯` → **Add connections**.
+
+**Integration capabilities** (set at notion.so/profile/integrations/internal → your integration → Capabilities):
+
+- Read-only commands: **Read content** only
+- `notion append`, `notion append --after`, `notion create-page` (page parent): also need **Insert content**
+- `notion create-page --parent <db>`: also need **Insert content** + database must be shared with integration
+- `notion edit-page`: also need **Update content** + **Insert content**
+- `notion comment`: also need **Read comments** + **Insert comments**
+
+---
+
+## Authentication
+
+Two auth methods are available. If both are configured, **OAuth takes precedence**.
+
+| Method            | Command                                           | Attribution         | Notes                                                   |
+| ----------------- | ------------------------------------------------- | ------------------- | ------------------------------------------------------- |
+| Interactive setup | `notion auth login`                               | —                   | Guides you to choose; TTY required                      |
+| OAuth user login  | select "OAuth user login" in `notion auth login`  | Your Notion account | Browser required; `--manual` for headless               |
+| Integration token | select "Integration token" in `notion auth login` | Integration bot     | Works in CI/headless; must connect integration to pages |
+
+```bash
+notion auth login                    # interactive selector — OAuth or integration token
+notion auth login --manual           # headless OAuth (prints URL, paste redirect back)
+notion auth status                   # show current auth state
+notion auth logout                   # remove a profile (interactive selector)
+notion auth logout --profile <name>  # remove specific profile directly
+notion auth list                     # list all saved profiles
+notion auth use <name>               # switch active profile
+notion --profile <name> <command>    # use a specific profile for one command
+```
+
+**Headless/CI agents:** Use `NOTION_API_TOKEN=<token>` env var — overrides all config, no TTY needed.
+
+---
+
+## Output Modes
+
+| Context        | Default           | Override |
+| -------------- | ----------------- | -------- |
+| Terminal (TTY) | Formatted tables  | `--json` |
+| Piped / agent  | Plain text tables | `--json` |
+
+`notion read` always outputs **markdown** — in terminal and when piped.
+
+Pipe any command to get JSON:
+
+```bash
+notion search "query" | jq '.[0].id'
+notion ls | jq '.[] | select(.type == "database")'
+```
+
+---
+
+## Commands
+
+### Search & Discovery
+
+```bash
+notion search "query"                    # search all pages/databases by title
+notion search "query" --type page        # pages only
+notion search "query" --type database    # databases only
+notion search "query" --sort asc         # sort by last edited time (asc or desc)
+notion ls                                # list everything accessible to integration
+notion ls --sort desc                    # sort by last edited time
+notion users                             # list workspace members
+notion comments <id|url>                 # list page comments
+notion open <id|url>                     # open in browser
+```
+
+### Reading Pages
+
+```bash
+notion read <id|url>          # markdown (always, even when piped)
+notion read <id|url> --json   # raw Notion JSON block tree
+```
+
+### Database Operations
+
+```bash
+notion db schema <id|url>                             # inspect properties + valid values
+notion db query <id|url>                              # all rows
+notion db query <id|url> --filter "Status=Done"       # filter (repeatable)
+notion db query <id|url> --sort "Created:desc"        # sort (repeatable)
+notion db query <id|url> --columns "Title,Status"     # limit columns
+notion db query <id|url> --json | jq '.[] | .properties'
+
+notion db create --parent <page-id|url> --title "My Database"  # create a new database
+```
+
+### Write Operations
+
+```bash
+notion append <id|url> -m "## Heading\nParagraph text"   # append markdown blocks to a page
+notion append <id|url> -m "$(cat notes.md)"              # append file contents
+
+notion create-page --parent <page-id|url> --title "Title"               # child page under a page
+notion create-page --parent <page-id|url> --title "Title" -m "# Hello"  # with markdown body
+echo "# Content" | notion create-page --parent <page-id|url> --title "Title"  # from stdin
+
+# Create entry in a database (auto-detected from parent ID)
+notion create-page --parent <db-id|url> --title "New Task"
+notion create-page --parent <db-id|url> --title "Task" --prop "Status=To Do" --prop "Priority=High"
+notion create-page --parent <db-id|url> --title "Task" --prop "Due=2026-04-01" -m "# Details"
+
+# Icon and cover
+notion create-page --parent <id|url> --title "Page" --icon "🚀"
+notion create-page --parent <id|url> --title "Page" --cover "https://example.com/img.jpg"
+
+URL=$(notion create-page --parent <id|url> --title "Summary" -m "...")   # capture URL
+
+notion comment <id|url> -m "Reviewed and approved."                  # add comment to a page
+notion comment <id|url> -m "Reply" --reply-to <discussion-id>        # reply to a discussion thread
+notion comment <id|url> -m "Note" --block <block-id>                 # comment on a specific block
+
+notion archive <id|url>                                              # move page to trash
+
+notion move <ids|urls...> --to <id|url>                              # move pages to a new parent page
+notion move <ids|urls...> --to-db <id|url>                           # move pages to a database parent
+```
+
+#### Updating Page Properties
+
+```bash
+notion update <id|url> --prop "Status=Done"                      # set a single property
+notion update <id|url> --prop "Status=Done" --prop "Priority=1"  # multiple properties
+notion update <id|url> --title "New Title"                       # set the title
+notion update <id|url> --prop "Due=2026-04-01"                   # set a date
+notion update <id|url> --prop "Tags=bug,urgent"                  # multi-select (comma-separated)
+notion update <id|url> --prop "Done=true"                        # checkbox (true/yes/false/no)
+notion update <id|url> --prop "Status="                          # clear a property (empty value)
+```
+
+Supported types: title, rich_text, select, status, multi_select, number, checkbox, url, email, phone_number, date.
+
+#### Surgical Editing
+
+Search-and-replace specific text, replace the full page, or insert content at a specific location.
+
+```bash
+# 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"
+
+# Pipe replacement content from a file
+cat updated-section.md | notion edit-page <id|url>
+
+# Allow deletion of child pages/databases during replace
+notion edit-page <id|url> -m "## Clean Slate" --allow-deleting-content
+
+# Append after a matched section (inserts new blocks right after the match)
+notion append <id|url> -m "New content" --after "## Status...end of status"
+```
+
+> **`--range` (deprecated):** The `--range` flag still works for backward compatibility but uses the older `replace_content_range` API. Prefer `--find`/`--replace` for targeted edits.
+
+---
+
+## ID Formats
+
+All commands accept any of:
+
+- `abc123def456789012345678901234ab` (32-char hex)
+- `abc123de-f456-7890-1234-5678901234ab` (UUID)
+- `https://www.notion.so/workspace/Page-Title-abc123` (full URL)
+
+---
+
+## Agent Patterns
+
+```bash
+# Find page by title, read it
+PAGE_ID=$(notion search "Meeting Notes" --type page | jq -r '.[0].id')
+notion read "$PAGE_ID"
+
+# Get database ID, then query with filter
+DB_ID=$(notion search "Project Tracker" --type database | jq -r '.[0].id')
+notion db query "$DB_ID" --filter "Status=In Progress" | jq '.[] | .properties'
+
+# Always check schema before filtering (see valid property names/values)
+notion db schema "$DB_ID"
+notion db query "$DB_ID" --filter "Status=Done"
+
+# Extract page section
+notion read "$PAGE_ID" | grep -A 10 "## Action Items"
+
+# Summarize a page and append the summary back
+SUMMARY=$(notion read "$PAGE_ID" | your-summarize-command)
+notion append "$PAGE_ID" -m "## AI Summary\n$SUMMARY"
+
+# Create a page and capture its URL for further use
+URL=$(notion create-page --parent "$PAGE_ID" --title "Report $(date +%Y-%m-%d)" -m "# Report\n...")
+echo "Created: $URL"
+
+# Pipe command output into a new page
+my-report-command | notion create-page --parent "$PAGE_ID" --title "Auto Report"
+
+# Surgically update specific text on a page
+# 1. Read the page to find the text you want to change
+notion read "$PAGE_ID"
+# 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"
+
+# Create a database entry with properties
+DB_ID=$(notion search "Tasks" --type database | jq -r '.[0].id')
+notion db schema "$DB_ID"   # check property names and valid values first
+notion create-page --parent "$DB_ID" --title "Fix login bug" \
+  --prop "Status=To Do" --prop "Priority=High" --prop "Due=2026-04-15"
+
+# Insert a new sub-section after an existing section
+notion append "$PAGE_ID" -m "## New Sub-section\nContent here" \
+  --after "## Existing Section...last line of section"
+
+# Move pages to a different parent
+ARCHIVE_ID=$(notion search "Archive" --type page | jq -r '.[0].id')
+notion move "$PAGE_ID" --to "$ARCHIVE_ID"
+
+# Move multiple pages into a database
+notion move page1-id page2-id --to-db "$DB_ID"
+```
+
+---
+
+## Troubleshooting
+
+**404 / page not found** — Share the page with your integration: page → `⋯` → **Add connections**.
+
+**401 / unauthorized** — Run `notion auth login` or set `NOTION_API_TOKEN`.
+
+**Search returns nothing** — Search is title-only. Page must be shared with integration.
+
+**Empty db query** — Run `notion db schema <id>` to see valid property names and values.
+
+**`notion auth login` requires TTY** — Use `NOTION_API_TOKEN` env var in agents, or use `notion auth login --manual` for headless OAuth.
+
+**`notion comment` returns "Insufficient permissions"** — Enable **Read comments** + **Insert comments** in integration capabilities: notion.so/profile/integrations/internal → your integration → Capabilities.
+
+**`notion append` / `notion create-page` returns "Insufficient permissions"** — Enable **Insert content** in integration capabilities.
+
+**`notion edit-page` returns "Insufficient permissions"** — Enable **Update content** in integration capabilities.
+
+**`--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/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync } from "fs";
-import { dirname, join as join3 } from "path";
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, join as join4 } from "path";
 import { fileURLToPath } from "url";
-import { Command as Command25 } from "commander";
+import { Command as Command26 } from "commander";
 
 // src/commands/append.ts
 import { Command } from "commander";
@@ -1436,7 +1436,7 @@ _notion_completion() {
   local cur prev words cword
   _init_completion || return
 
-  local commands="init profile completion --help --version --verbose --color"
+  local commands="init profile completion skill --help --version --verbose --color"
   local profile_commands="list use remove"
 
   case "$prev" in
@@ -1469,6 +1469,7 @@ _notion() {
     'init:authenticate with Notion and save a profile'
     'profile:manage authentication profiles'
     'completion:output shell completion script'
+    'skill:install the agent skill file'
   )
 
   local -a global_opts
@@ -1520,6 +1521,7 @@ complete -c notion -l color -d 'force color output'
 complete -c notion -n '__fish_use_subcommand' -a init -d 'authenticate with Notion and save a profile'
 complete -c notion -n '__fish_use_subcommand' -a profile -d 'manage authentication profiles'
 complete -c notion -n '__fish_use_subcommand' -a completion -d 'output shell completion script'
+complete -c notion -n '__fish_use_subcommand' -a skill -d 'install the agent skill file'
 
 # profile subcommands
 complete -c notion -n '__fish_seen_subcommand_from profile' -a list -d 'list all authentication profiles'
@@ -2899,14 +2901,140 @@ function searchCommand() {
   return cmd;
 }
 
-// src/commands/update.ts
+// src/commands/skill.ts
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync
+} from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname, join as join3 } from "path";
+import chalk from "chalk";
 import { Command as Command23 } from "commander";
+function skillPath() {
+  if (!process.argv[1]) {
+    throw new Error("Cannot determine install path. Run with: notion skill");
+  }
+  const entryPoint = realpathSync(process.argv[1]);
+  const packageRoot = dirname(dirname(entryPoint));
+  const candidates = [
+    join3(packageRoot, ".agents", "skills", "using-notion-cli", "SKILL.md"),
+    join3(
+      dirname(entryPoint),
+      "..",
+      ".agents",
+      "skills",
+      "using-notion-cli",
+      "SKILL.md"
+    )
+  ];
+  for (const c2 of candidates) {
+    if (existsSync(c2)) return c2;
+  }
+  throw new Error(
+    "SKILL.md not found. Reinstall with: npm install -g @andrzejchm/notion-cli"
+  );
+}
+function getAgentTargets() {
+  const home = homedir2();
+  const targets = [
+    {
+      name: "Claude Code",
+      dir: join3(home, ".claude", "skills", "using-notion-cli")
+    },
+    { name: "Codex", dir: join3(home, ".agents", "skills", "using-notion-cli") },
+    {
+      name: "OpenCode",
+      dir: join3(home, ".config", "opencode", "skills", "using-notion-cli")
+    }
+  ];
+  return targets.map((t) => ({
+    ...t,
+    detected: existsSync(dirname(t.dir))
+  }));
+}
+function installTo(source, target) {
+  if (!existsSync(target.dir)) mkdirSync(target.dir, { recursive: true });
+  const dest = join3(target.dir, "SKILL.md");
+  copyFileSync(source, dest);
+  return dest;
+}
+async function installInteractive(source, targets) {
+  const { checkbox } = await import("@inquirer/prompts");
+  const selected = await checkbox({
+    message: "Install skill for which agents?",
+    choices: targets.map((t) => ({
+      name: `${t.name}${t.detected ? chalk.dim(" (detected)") : ""}`,
+      value: t.name,
+      checked: t.detected
+    }))
+  });
+  if (selected.length === 0) {
+    process.stderr.write("No agents selected.\n");
+    return;
+  }
+  process.stdout.write("\n");
+  for (const name of selected) {
+    const target = targets.find((t) => t.name === name);
+    if (!target) continue;
+    const dest = installTo(source, target);
+    process.stdout.write(`  Installed: ${target.name}: ${dest}
+`);
+  }
+}
+function installNonInteractive(source, targets) {
+  const detected = targets.filter((t) => t.detected);
+  if (detected.length === 0) {
+    process.stderr.write(
+      "No agents detected. Use --path to specify install location:\n  notion skill --path ~/.claude/skills/using-notion-cli/SKILL.md\n"
+    );
+    return;
+  }
+  for (const target of detected) {
+    const dest = installTo(source, target);
+    process.stdout.write(`Installed: ${target.name}: ${dest}
+`);
+  }
+}
+function skillCommand() {
+  const cmd = new Command23("skill");
+  cmd.description("Install the agent skill file for your coding agents").option("--print", "Print the skill file content instead of installing").option("--path <path>", "Install to a specific file path").action(
+    withErrorHandling(async (opts) => {
+      if (opts.print) {
+        process.stdout.write(readFileSync(skillPath(), "utf-8"));
+        return;
+      }
+      const source = skillPath();
+      if (opts.path) {
+        const dir = dirname(opts.path);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        copyFileSync(source, opts.path);
+        process.stdout.write(`Installed to ${opts.path}
+`);
+        return;
+      }
+      const targets = getAgentTargets();
+      const isTTY = process.stdout.isTTY ?? false;
+      if (isTTY) {
+        await installInteractive(source, targets);
+      } else {
+        installNonInteractive(source, targets);
+      }
+    })
+  );
+  return cmd;
+}
+
+// src/commands/update.ts
+import { Command as Command24 } from "commander";
 function collectProps3(val, acc) {
   acc.push(val);
   return acc;
 }
 function updateCommand() {
-  const cmd = new Command23("update");
+  const cmd = new Command24("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)",
@@ -2964,7 +3092,7 @@ function updateCommand() {
 }
 
 // src/commands/users.ts
-import { Command as Command24 } from "commander";
+import { Command as Command25 } from "commander";
 function getEmailOrWorkspace(user) {
   if (user.type === "person") {
     return user.person.email ?? "\u2014";
@@ -2976,7 +3104,7 @@ function getEmailOrWorkspace(user) {
   return "\u2014";
 }
 function usersCommand() {
-  const cmd = new Command24("users");
+  const cmd = new Command25("users");
   cmd.description("list all users in the workspace").option("--json", "output as JSON").action(
     withErrorHandling(async (opts) => {
       if (opts.json) setOutputMode("json");
@@ -3003,11 +3131,11 @@ function usersCommand() {
 
 // src/cli.ts
 var __filename = fileURLToPath(import.meta.url);
-var __dirname = dirname(__filename);
+var __dirname = dirname2(__filename);
 var pkg = JSON.parse(
-  readFileSync(join3(__dirname, "../package.json"), "utf-8")
+  readFileSync2(join4(__dirname, "../package.json"), "utf-8")
 );
-var program = new Command25();
+var program = new Command26();
 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({
@@ -3028,7 +3156,7 @@ program.hook("preAction", (thisCommand) => {
     setOutputMode("md");
   }
 });
-var authCmd = new Command25("auth").description("manage Notion authentication");
+var authCmd = new Command26("auth").description("manage Notion authentication");
 authCmd.action(authDefaultAction(authCmd));
 authCmd.addCommand(loginCommand());
 authCmd.addCommand(logoutCommand());
@@ -3038,7 +3166,7 @@ authCmd.addCommand(profileUseCommand());
 authCmd.addCommand(profileRemoveCommand());
 program.addCommand(authCmd);
 program.addCommand(initCommand(), { hidden: true });
-var profileCmd = new Command25("profile").description(
+var profileCmd = new Command26("profile").description(
   "manage authentication profiles"
 );
 profileCmd.addCommand(profileListCommand());
@@ -3058,11 +3186,12 @@ program.addCommand(editPageCommand());
 program.addCommand(updateCommand());
 program.addCommand(archiveCommand());
 program.addCommand(moveCommand());
-var dbCmd = new Command25("db").description("Database operations");
+var dbCmd = new Command26("db").description("Database operations");
 dbCmd.addCommand(dbCreateCommand());
 dbCmd.addCommand(dbSchemaCommand());
 dbCmd.addCommand(dbQueryCommand());
 program.addCommand(dbCmd);
 program.addCommand(completionCommand());
+program.addCommand(skillCommand());
 await program.parseAsync();
 //# sourceMappingURL=cli.js.map