@andrzejchm/notion-cli 0.9.1 → 0.11.0

package/{docs → .agents}/skills/using-notion-cli/SKILL.md

@@ -1,17 +1,25 @@
 ---
 name: using-notion-cli
-description: Reads and writes Notion pages using the `notion` CLI tool. Use when accessing Notion content, searching workspace pages, querying database entries, reading page markdown, appending content, creating pages, or adding comments from the terminal or within automated workflows.
+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
 ```
@@ -21,6 +29,7 @@ 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
@@ -33,11 +42,11 @@ Pages must be shared with your integration: open page → `⋯` → **Add connec
 
 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 |
+| 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
@@ -47,6 +56,7 @@ 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.
@@ -55,14 +65,15 @@ notion auth use <name>               # switch active profile
 
 ## Output Modes
 
-| Context | Default | Override |
-|---------|---------|----------|
-| Terminal (TTY) | Formatted tables | `--json` |
-| Piped / agent | Plain text tables | `--json` |
+| 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")'
@@ -78,7 +89,9 @@ notion ls | jq '.[] | select(.type == "database")'
 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
@@ -100,6 +113,8 @@ 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
@@ -123,7 +138,14 @@ notion create-page --parent <id|url> --title "Page" --cover "https://example.com
 
 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 "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
@@ -174,6 +196,7 @@ notion append <id|url> -m "New content" --after "## Status...end of status"
 ## 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)
@@ -229,6 +252,13 @@ notion create-page --parent "$DB_ID" --title "Fix login bug" \
 # 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"
 ```
 
 ---

package/README.md

@@ -107,6 +107,8 @@ notion ls
 | `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 archive <id\|url>` | Archive (trash) a page |
+| `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 |
 | `notion completion bash\|zsh\|fish` | Install shell tab completion |
 
 ### `notion search` / `notion ls` flags

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 Command24 } 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'
@@ -2479,13 +2481,71 @@ function lsCommand() {
   return cmd;
 }
 
+// src/commands/move.ts
+import { Command as Command16 } from "commander";
+function moveCommand() {
+  const cmd = new Command16("move");
+  cmd.description("move pages to a new parent").argument("<ids/urls...>", "Notion page IDs or URLs to move").option("--to <id/url>", "target page parent ID or URL").option(
+    "--to-db <id/url>",
+    "target database parent ID or URL (resolves to data source)"
+  ).action(
+    withErrorHandling(async (idsOrUrls, opts) => {
+      if (!opts.to && !opts.toDb) {
+        throw new CliError(
+          ErrorCodes.INVALID_ARG,
+          "No target parent specified.",
+          "Provide --to <page-id> or --to-db <database-id>"
+        );
+      }
+      if (opts.to && opts.toDb) {
+        throw new CliError(
+          ErrorCodes.INVALID_ARG,
+          "Cannot specify both --to and --to-db.",
+          "Provide only one: --to <page-id> or --to-db <database-id>"
+        );
+      }
+      const { token, source } = await resolveToken();
+      reportTokenSource(source);
+      const client = createNotionClient(token);
+      let parent;
+      if (opts.toDb) {
+        const dsId = await resolveDataSourceId(client, opts.toDb);
+        parent = { type: "data_source_id", data_source_id: dsId };
+      } else if (opts.to) {
+        const targetId = toUuid(parseNotionId(opts.to));
+        parent = { type: "page_id", page_id: targetId };
+      } else {
+        throw new CliError(
+          ErrorCodes.INVALID_ARG,
+          "No target parent specified."
+        );
+      }
+      const results = [];
+      for (const idOrUrl of idsOrUrls) {
+        const uuid = toUuid(parseNotionId(idOrUrl));
+        const result = await client.pages.move({ page_id: uuid, parent });
+        results.push(result);
+      }
+      const mode = getOutputMode();
+      if (mode === "json") {
+        process.stdout.write(`${formatJSON(results)}
+`);
+      } else {
+        process.stdout.write(`Moved ${results.length} page(s).
+`);
+      }
+    })
+  );
+  return cmd;
+}
+
 // src/commands/open.ts
 import { exec } from "child_process";
 import { promisify } from "util";
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 var execAsync = promisify(exec);
 function openCommand() {
-  const cmd = new Command16("open");
+  const cmd = new Command17("open");
   cmd.description("open a Notion page in the default browser").argument("<id/url>", "Notion page ID or URL").action(
     withErrorHandling(async (idOrUrl) => {
       const id = parseNotionId(idOrUrl);
@@ -2501,9 +2561,9 @@ function openCommand() {
 }
 
 // src/commands/profile/list.ts
-import { Command as Command17 } from "commander";
+import { Command as Command18 } from "commander";
 function profileListCommand() {
-  const cmd = new Command17("list");
+  const cmd = new Command18("list");
   cmd.description("list all authentication profiles").action(
     withErrorHandling(async () => {
       const config = await readGlobalConfig();
@@ -2532,9 +2592,9 @@ function profileListCommand() {
 }
 
 // src/commands/profile/remove.ts
-import { Command as Command18 } from "commander";
+import { Command as Command19 } from "commander";
 function profileRemoveCommand() {
-  const cmd = new Command18("remove");
+  const cmd = new Command19("remove");
   cmd.description("remove an authentication profile").argument("<name>", "profile name to remove").action(
     withErrorHandling(async (name) => {
       const config = await readGlobalConfig();
@@ -2560,9 +2620,9 @@ function profileRemoveCommand() {
 }
 
 // src/commands/profile/use.ts
-import { Command as Command19 } from "commander";
+import { Command as Command20 } from "commander";
 function profileUseCommand() {
-  const cmd = new Command19("use");
+  const cmd = new Command20("use");
   cmd.description("switch the active profile").argument("<name>", "profile name to activate").action(
     withErrorHandling(async (name) => {
       const config = await readGlobalConfig();
@@ -2585,7 +2645,7 @@ function profileUseCommand() {
 }
 
 // src/commands/read.ts
-import { Command as Command20 } from "commander";
+import { Command as Command21 } from "commander";
 
 // src/output/markdown.ts
 import { Chalk as Chalk2 } from "chalk";
@@ -2725,7 +2785,7 @@ async function fetchPageMarkdown(client, pageId) {
 
 // src/commands/read.ts
 function readCommand() {
-  return new Command20("read").description("Read a Notion page as markdown").argument("<id>", "Notion page ID or URL").action(
+  return new Command21("read").description("Read a Notion page as markdown").argument("<id>", "Notion page ID or URL").action(
     withErrorHandling(async (id) => {
       const { token } = await resolveToken();
       const client = createNotionClient(token);
@@ -2751,7 +2811,7 @@ function readCommand() {
 
 // src/commands/search.ts
 import { isFullPageOrDataSource as isFullPageOrDataSource2 } from "@notionhq/client";
-import { Command as Command21 } from "commander";
+import { Command as Command22 } from "commander";
 function getTitle2(item) {
   if (item.object === "data_source") {
     return item.title.map((t) => t.plain_text).join("") || "(untitled)";
@@ -2771,7 +2831,7 @@ function displayType2(item) {
   return item.object === "data_source" ? "database" : item.object;
 }
 function searchCommand() {
-  const cmd = new Command21("search");
+  const cmd = new Command22("search");
   cmd.description("search Notion workspace by keyword").argument("<query>", "search keyword").option(
     "--type <type>",
     "filter by object type (page or database)",
@@ -2841,14 +2901,140 @@ function searchCommand() {
   return cmd;
 }
 
+// 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 Command22 } from "commander";
+import { Command as Command24 } from "commander";
 function collectProps3(val, acc) {
   acc.push(val);
   return acc;
 }
 function updateCommand() {
-  const cmd = new Command22("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)",
@@ -2906,7 +3092,7 @@ function updateCommand() {
 }
 
 // src/commands/users.ts
-import { Command as Command23 } from "commander";
+import { Command as Command25 } from "commander";
 function getEmailOrWorkspace(user) {
   if (user.type === "person") {
     return user.person.email ?? "\u2014";
@@ -2918,7 +3104,7 @@ function getEmailOrWorkspace(user) {
   return "\u2014";
 }
 function usersCommand() {
-  const cmd = new Command23("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");
@@ -2945,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 Command24();
+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({
@@ -2970,7 +3156,7 @@ program.hook("preAction", (thisCommand) => {
     setOutputMode("md");
   }
 });
-var authCmd = new Command24("auth").description("manage Notion authentication");
+var authCmd = new Command26("auth").description("manage Notion authentication");
 authCmd.action(authDefaultAction(authCmd));
 authCmd.addCommand(loginCommand());
 authCmd.addCommand(logoutCommand());
@@ -2980,7 +3166,7 @@ authCmd.addCommand(profileUseCommand());
 authCmd.addCommand(profileRemoveCommand());
 program.addCommand(authCmd);
 program.addCommand(initCommand(), { hidden: true });
-var profileCmd = new Command24("profile").description(
+var profileCmd = new Command26("profile").description(
   "manage authentication profiles"
 );
 profileCmd.addCommand(profileListCommand());
@@ -2999,11 +3185,13 @@ program.addCommand(createPageCommand());
 program.addCommand(editPageCommand());
 program.addCommand(updateCommand());
 program.addCommand(archiveCommand());
-var dbCmd = new Command24("db").description("Database operations");
+program.addCommand(moveCommand());
+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