{
  "schemaVersion": "1.0",
  "item": {
    "slug": "vibe-notionbot",
    "name": "Vibe Notionbot",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/devxoul/vibe-notionbot",
    "canonicalUrl": "https://clawhub.ai/devxoul/vibe-notionbot",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/vibe-notionbot",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=vibe-notionbot",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/vibe-notionbot"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/vibe-notionbot",
    "agentPageUrl": "https://openagent3.xyz/skills/vibe-notionbot/agent",
    "manifestUrl": "https://openagent3.xyz/skills/vibe-notionbot/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/vibe-notionbot/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Vibe Notionbot",
        "body": "A TypeScript CLI tool that enables AI agents and humans to interact with Notion workspaces through the official Notion API. Supports pages, databases, blocks, users, comments, and search."
      },
      {
        "title": "Which CLI to Use",
        "body": "This package ships two CLIs. Pick the right one based on your situation:\n\nvibe-notionvibe-notionbot (this CLI)APIUnofficial private APIOfficial Notion APIAuthtoken_v2 auto-extracted from Notion desktop appNOTION_TOKEN env var (Integration token)IdentityActs as the userActs as a botSetupZero — credentials extracted automaticallyManual — create Integration at notion.so/my-integrationsDatabase rowsadd-row, update-rowCreate via page create --databaseView managementview-get, view-update, view-list, view-add, view-deleteNot supportedWorkspace listingSupportedNot supportedStabilityPrivate API — may break on Notion changesOfficial versioned API — stable\n\nDecision flow:\n\nIf the Notion desktop app is installed → use vibe-notion\nIf NOTION_TOKEN is set but no desktop app → use vibe-notionbot (this CLI)\nIf both are available → prefer vibe-notion (broader capabilities, zero setup)\nIf neither → ask the user to set up one of the two"
      },
      {
        "title": "Important: CLI Only",
        "body": "Never call the Notion API directly. Always use the vibe-notionbot CLI commands described in this skill. Do not make raw HTTP requests to the Notion API or use @notionhq/client directly. Direct API calls risk exposing credentials and may trigger Notion's abuse detection, getting the user's account blocked.\n\nIf a feature you need is not supported by vibe-notionbot, let the user know and offer to file a feature request at devxoul/vibe-notion on their behalf. Before submitting, strip out any real user data — IDs, names, emails, tokens, page content, or anything else that could identify the user or their workspace. Use generic placeholders instead and keep the issue focused on describing the missing capability."
      },
      {
        "title": "Important: Never Write Scripts",
        "body": "Never write scripts (Python, TypeScript, Bash, etc.) to automate Notion operations. The batch command already handles bulk operations of any size. Writing a script to loop through API calls is always wrong — use batch with --file instead.\n\nThis applies even when:\n\nYou need to create 100+ rows or pages\nYou need cross-references between newly created items (use multi-pass batch — see Bulk Operations Strategy)\nThe operation feels \"too big\" for a single command\n\nIf you catch yourself thinking \"I should write a script for this,\" stop and use batch."
      },
      {
        "title": "Quick Start",
        "body": "# Check authentication status\nvibe-notionbot auth status\n\n# Search for a page or database\nvibe-notionbot search \"Project Roadmap\"\n\n# List all databases\nvibe-notionbot database list\n\n# Create a new page\nvibe-notionbot page create --parent <parent_id> --title \"My New Page\""
      },
      {
        "title": "Integration Token (Official API)",
        "body": "Set the NOTION_TOKEN environment variable with your integration token from the Notion Developer Portal.\n\nexport NOTION_TOKEN=secret_xxx\nvibe-notionbot auth status\n\nThe integration token provides access to the official Notion API (@notionhq/client)."
      },
      {
        "title": "Page Commands",
        "body": "# Retrieve a page\nvibe-notionbot page get <page_id>\n\n# Create a new page under a parent page or database\nvibe-notionbot page create --parent <parent_id> --title \"New Page Title\"\nvibe-notionbot page create --parent <database_id> --title \"New Database Item\" --database\n\n# Create a page with markdown content\nvibe-notionbot page create --parent <parent_id> --title \"My Doc\" --markdown '# Hello\\n\\nThis is **bold** text.'\n\n# Create a page with markdown from a file\nvibe-notionbot page create --parent <parent_id> --title \"My Doc\" --markdown-file ./content.md\n\n# Create a page with markdown containing local images (auto-uploaded to Notion)\nvibe-notionbot page create --parent <parent_id> --title \"My Doc\" --markdown-file ./doc-with-images.md\n\n# Update page properties\nvibe-notionbot page update <page_id> --set \"Status=In Progress\" --set \"Priority=High\"\n\n# Replace all content on a page with new markdown\nvibe-notionbot page update <page_id> --replace-content --markdown '# New Content'\nvibe-notionbot page update <page_id> --replace-content --markdown-file ./updated.md\n\n# Archive (delete) a page\nvibe-notionbot page archive <page_id>\n\n# Retrieve a specific page property\nvibe-notionbot page property <page_id> <property_id>"
      },
      {
        "title": "Database Commands",
        "body": "# Retrieve a database schema\nvibe-notionbot database get <database_id>\n\n# Query a database with optional filters and sorts\nvibe-notionbot database query <database_id> --filter '{\"property\": \"Status\", \"select\": {\"equals\": \"In Progress\"}}'\nvibe-notionbot database query <database_id> --sort '[{\"property\": \"Created time\", \"direction\": \"descending\"}]'\nvibe-notionbot database query <database_id> --page-size 10 --start-cursor <cursor>\n\n# Create a database under a parent page\nvibe-notionbot database create --parent <page_id> --title \"My Database\" --properties '{\"Name\": {\"title\": {}}}'\n\n# Update a database schema or title\nvibe-notionbot database update <database_id> --title \"Updated Title\"\nvibe-notionbot database update <database_id> --properties '{\"Status\": {\"select\": {\"options\": [{\"name\": \"Active\"}, {\"name\": \"Archived\"}]}}}'\nvibe-notionbot database update <database_id> --title \"Updated Title\" --properties '{\"Status\": {\"select\": {}}}'\n\n# Delete a property from a database\nvibe-notionbot database delete-property <database_id> --property \"Status\"\n\n# List all databases accessible by the integration\nvibe-notionbot database list\nvibe-notionbot database list --page-size 10 --start-cursor <cursor>"
      },
      {
        "title": "Block Commands",
        "body": "# Retrieve a block\nvibe-notionbot block get <block_id>\n\n# List direct children of a block (paginated)\nvibe-notionbot block children <block_id>\nvibe-notionbot block children <block_id> --page-size 50 --start-cursor <cursor>\n\n# Append child blocks to a parent\nvibe-notionbot block append <parent_id> --content '[{\"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Hello World\"}}]}}]'\n\n# Append markdown content as blocks\nvibe-notionbot block append <parent_id> --markdown '# Hello\\n\\nThis is **bold** text.'\n\n# Append markdown from a file\nvibe-notionbot block append <parent_id> --markdown-file ./content.md\n\n# Append markdown with local images (auto-uploaded to Notion)\nvibe-notionbot block append <parent_id> --markdown-file ./doc-with-images.md\n\n# Append nested markdown (indented lists become nested children blocks)\nvibe-notionbot block append <parent_id> --markdown '- Parent item\\n  - Child item\\n    - Grandchild item'\n\n# Append blocks after a specific block (positional insertion)\nvibe-notionbot block append <parent_id> --after <block_id> --markdown '# Inserted after specific block'\nvibe-notionbot block append <parent_id> --after <block_id> --content '[{\"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Inserted after\"}}]}}]'\n\n# Append blocks before a specific block\nvibe-notionbot block append <parent_id> --before <block_id> --markdown '# Inserted before specific block'\n\n# Update a block's content\nvibe-notionbot block update <block_id> --content '{\"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Updated content\"}}]}}'\n\n# Delete (archive) a block\nvibe-notionbot block delete <block_id>\n\n# Upload a file as a block (image or file block)\nvibe-notionbot block upload <parent_id> --file ./image.png --pretty\nvibe-notionbot block upload <parent_id> --file ./document.pdf --pretty\nvibe-notionbot block upload <parent_id> --file ./image.png --after <block_id> --pretty\nvibe-notionbot block upload <parent_id> --file ./image.png --before <block_id> --pretty"
      },
      {
        "title": "User Commands",
        "body": "# List all users in the workspace\nvibe-notionbot user list\nvibe-notionbot user list --page-size 10 --start-cursor <cursor>\n\n# Get info for a specific user\nvibe-notionbot user get <user_id>\n\n# Get info for the current bot/integration\nvibe-notionbot user me"
      },
      {
        "title": "Search Commands",
        "body": "# Search across the entire workspace\nvibe-notionbot search \"query text\"\n\n# Filter search by object type\nvibe-notionbot search \"Project\" --filter page\nvibe-notionbot search \"Tasks\" --filter database\n\n# Sort search results\nvibe-notionbot search \"Meeting\" --sort desc\n\n# Paginate search results\nvibe-notionbot search \"Notes\" --page-size 10 --start-cursor <cursor>"
      },
      {
        "title": "Comment Commands",
        "body": "# List comments on a page\nvibe-notionbot comment list --page <page_id>\nvibe-notionbot comment list --page <page_id> --page-size 10 --start-cursor <cursor>\n\n# List inline comments on a specific block\nvibe-notionbot comment list --block <block_id>\n\n# Create a comment on a page\nvibe-notionbot comment create \"This is a comment\" --page <page_id>\n\n# Reply to a comment thread (discussion)\nvibe-notionbot comment create \"Replying to thread\" --discussion <discussion_id>\n\n# Retrieve a specific comment\nvibe-notionbot comment get <comment_id>"
      },
      {
        "title": "Batch Operations",
        "body": "Run multiple write operations in a single CLI call. Use this instead of calling the CLI repeatedly when you need to create, update, or delete multiple things at once. Saves tokens and reduces round-trips.\n\n# Inline JSON (no --workspace-id needed, uses NOTION_TOKEN)\nvibe-notionbot batch '<operations_json>'\n\n# From file (for large payloads)\nvibe-notionbot batch --file ./operations.json '[]'\n\nSupported actions (11 total):\n\nActionDescriptionpage.createCreate a pagepage.updateUpdate page propertiespage.archiveArchive a pageblock.appendAppend blocks to a parentblock.updateUpdate a blockblock.deleteDelete a blockcomment.createCreate a commentdatabase.createCreate a databasedatabase.updateUpdate database title or schemadatabase.delete-propertyDelete a database propertyblock.uploadUpload a file as an image or file block\n\nOperation format: Each operation is an object with action plus the same fields you'd pass to the individual command handler. Example with mixed actions:\n\n[\n  {\"action\": \"page.create\", \"parent\": \"<parent_id>\", \"title\": \"Meeting Notes\"},\n  {\"action\": \"block.append\", \"parent_id\": \"<page_id>\", \"markdown\": \"# Agenda\\n\\n- Item 1\\n- Item 2\"},\n  {\"action\": \"comment.create\", \"content\": \"Page created via batch\", \"page\": \"<page_id>\"}\n]\n\nOutput format:\n\n{\n  \"results\": [\n    {\"index\": 0, \"action\": \"page.create\", \"success\": true, \"data\": {\"id\": \"page-uuid\", \"...\": \"...\"}},\n    {\"index\": 1, \"action\": \"block.append\", \"success\": true, \"data\": {\"...\": \"...\"}},\n    {\"index\": 2, \"action\": \"comment.create\", \"success\": true, \"data\": {\"id\": \"comment-uuid\", \"...\": \"...\"}}\n  ],\n  \"total\": 3,\n  \"succeeded\": 3,\n  \"failed\": 0\n}\n\nFail-fast behavior: Operations run sequentially. If any operation fails, execution stops immediately. The output will contain results for all completed operations plus the failed one. The process exits with code 1 on failure, 0 on success.\n\n{\n  \"results\": [\n    {\"index\": 0, \"action\": \"page.create\", \"success\": true, \"data\": {\"...\": \"...\"}},\n    {\"index\": 1, \"action\": \"block.append\", \"success\": false, \"error\": \"Block not found\"}\n  ],\n  \"total\": 3,\n  \"succeeded\": 1,\n  \"failed\": 1\n}"
      },
      {
        "title": "Bulk Operations Strategy",
        "body": "For large operations (tens or hundreds of items), use --file to avoid shell argument limits and keep things manageable.\n\nStep 1: Write the operations JSON to a file, then run batch with --file:\n\n# Write operations to a file (using your Write tool), then:\nvibe-notionbot batch --file ./operations.json '[]'\n\nMulti-pass pattern — when new items need to reference each other (e.g., a page property linking to another newly created page):\n\nPass 1 — Create all items (without cross-references): Write a batch JSON file with all create operations, omitting properties that point to other new items. Run it. Collect the returned IDs from the output.\nPass 2 — Set cross-references: Write a second batch JSON file with update operations that set the referencing properties using the IDs from Pass 1. Run it.\n\nPass 1: Create items A, B, C (no cross-refs) → get IDs for A, B, C\nPass 2: Update A.related=B, C.parent_ref=A (using real IDs from Pass 1)\n\nThis is the same result as a script, but without writing any code. Just two batch calls."
      },
      {
        "title": "Rate Limits",
        "body": "Notion enforces rate limits on its API. Batch operations run sequentially, so a large batch (30+ operations) can trigger 429 Too Many Requests errors. To avoid this:\n\nSplit large batches into chunks of ~25-30 operations per batch call\nIf a batch fails mid-way with a 429, re-run with only the remaining (unprocessed) operations\nThe batch output shows which operations succeeded before the failure — use the index field to determine where to resume"
      },
      {
        "title": "JSON (Default)",
        "body": "All commands output JSON by default for AI consumption:\n\n{\n  \"id\": \"...\",\n  \"object\": \"page\",\n  \"properties\": { ... }\n}"
      },
      {
        "title": "Pretty (Human-Readable)",
        "body": "Use --pretty flag for formatted output:\n\nvibe-notionbot search \"Project\" --pretty"
      },
      {
        "title": "Error Handling",
        "body": "Common errors from the Notion API:\n\nobject_not_found: The ID is incorrect or the integration doesn't have access.\nunauthorized: The NOTION_TOKEN is invalid.\nrate_limited: Too many requests."
      },
      {
        "title": "vibe-notionbot: command not found",
        "body": "The vibe-notion package is not installed. Run it directly using a package runner. Ask the user which one to use:\n\nnpx -y -p vibe-notion vibe-notionbot ...\nbunx -p vibe-notion vibe-notionbot ...\npnpm dlx --package vibe-notion vibe-notionbot ...\n\nIf you already know the user's preferred package runner, use it directly instead of asking."
      },
      {
        "title": "Limitations",
        "body": "Supports Notion API version 2025-09-03.\nDoes not support OAuth (token only).\nFile uploads are supported via block upload.\nPage property updates are limited to simple key=value pairs via --set."
      }
    ],
    "body": "Vibe Notionbot\n\nA TypeScript CLI tool that enables AI agents and humans to interact with Notion workspaces through the official Notion API. Supports pages, databases, blocks, users, comments, and search.\n\nWhich CLI to Use\n\nThis package ships two CLIs. Pick the right one based on your situation:\n\n\tvibe-notion\tvibe-notionbot (this CLI)\nAPI\tUnofficial private API\tOfficial Notion API\nAuth\ttoken_v2 auto-extracted from Notion desktop app\tNOTION_TOKEN env var (Integration token)\nIdentity\tActs as the user\tActs as a bot\nSetup\tZero — credentials extracted automatically\tManual — create Integration at notion.so/my-integrations\nDatabase rows\tadd-row, update-row\tCreate via page create --database\nView management\tview-get, view-update, view-list, view-add, view-delete\tNot supported\nWorkspace listing\tSupported\tNot supported\nStability\tPrivate API — may break on Notion changes\tOfficial versioned API — stable\n\nDecision flow:\n\nIf the Notion desktop app is installed → use vibe-notion\nIf NOTION_TOKEN is set but no desktop app → use vibe-notionbot (this CLI)\nIf both are available → prefer vibe-notion (broader capabilities, zero setup)\nIf neither → ask the user to set up one of the two\nImportant: CLI Only\n\nNever call the Notion API directly. Always use the vibe-notionbot CLI commands described in this skill. Do not make raw HTTP requests to the Notion API or use @notionhq/client directly. Direct API calls risk exposing credentials and may trigger Notion's abuse detection, getting the user's account blocked.\n\nIf a feature you need is not supported by vibe-notionbot, let the user know and offer to file a feature request at devxoul/vibe-notion on their behalf. Before submitting, strip out any real user data — IDs, names, emails, tokens, page content, or anything else that could identify the user or their workspace. Use generic placeholders instead and keep the issue focused on describing the missing capability.\n\nImportant: Never Write Scripts\n\nNever write scripts (Python, TypeScript, Bash, etc.) to automate Notion operations. The batch command already handles bulk operations of any size. Writing a script to loop through API calls is always wrong — use batch with --file instead.\n\nThis applies even when:\n\nYou need to create 100+ rows or pages\nYou need cross-references between newly created items (use multi-pass batch — see Bulk Operations Strategy)\nThe operation feels \"too big\" for a single command\n\nIf you catch yourself thinking \"I should write a script for this,\" stop and use batch.\n\nQuick Start\n# Check authentication status\nvibe-notionbot auth status\n\n# Search for a page or database\nvibe-notionbot search \"Project Roadmap\"\n\n# List all databases\nvibe-notionbot database list\n\n# Create a new page\nvibe-notionbot page create --parent <parent_id> --title \"My New Page\"\n\nAuthentication\nIntegration Token (Official API)\n\nSet the NOTION_TOKEN environment variable with your integration token from the Notion Developer Portal.\n\nexport NOTION_TOKEN=secret_xxx\nvibe-notionbot auth status\n\n\nThe integration token provides access to the official Notion API (@notionhq/client).\n\nCommands\nPage Commands\n# Retrieve a page\nvibe-notionbot page get <page_id>\n\n# Create a new page under a parent page or database\nvibe-notionbot page create --parent <parent_id> --title \"New Page Title\"\nvibe-notionbot page create --parent <database_id> --title \"New Database Item\" --database\n\n# Create a page with markdown content\nvibe-notionbot page create --parent <parent_id> --title \"My Doc\" --markdown '# Hello\\n\\nThis is **bold** text.'\n\n# Create a page with markdown from a file\nvibe-notionbot page create --parent <parent_id> --title \"My Doc\" --markdown-file ./content.md\n\n# Create a page with markdown containing local images (auto-uploaded to Notion)\nvibe-notionbot page create --parent <parent_id> --title \"My Doc\" --markdown-file ./doc-with-images.md\n\n# Update page properties\nvibe-notionbot page update <page_id> --set \"Status=In Progress\" --set \"Priority=High\"\n\n# Replace all content on a page with new markdown\nvibe-notionbot page update <page_id> --replace-content --markdown '# New Content'\nvibe-notionbot page update <page_id> --replace-content --markdown-file ./updated.md\n\n# Archive (delete) a page\nvibe-notionbot page archive <page_id>\n\n# Retrieve a specific page property\nvibe-notionbot page property <page_id> <property_id>\n\nDatabase Commands\n# Retrieve a database schema\nvibe-notionbot database get <database_id>\n\n# Query a database with optional filters and sorts\nvibe-notionbot database query <database_id> --filter '{\"property\": \"Status\", \"select\": {\"equals\": \"In Progress\"}}'\nvibe-notionbot database query <database_id> --sort '[{\"property\": \"Created time\", \"direction\": \"descending\"}]'\nvibe-notionbot database query <database_id> --page-size 10 --start-cursor <cursor>\n\n# Create a database under a parent page\nvibe-notionbot database create --parent <page_id> --title \"My Database\" --properties '{\"Name\": {\"title\": {}}}'\n\n# Update a database schema or title\nvibe-notionbot database update <database_id> --title \"Updated Title\"\nvibe-notionbot database update <database_id> --properties '{\"Status\": {\"select\": {\"options\": [{\"name\": \"Active\"}, {\"name\": \"Archived\"}]}}}'\nvibe-notionbot database update <database_id> --title \"Updated Title\" --properties '{\"Status\": {\"select\": {}}}'\n\n# Delete a property from a database\nvibe-notionbot database delete-property <database_id> --property \"Status\"\n\n# List all databases accessible by the integration\nvibe-notionbot database list\nvibe-notionbot database list --page-size 10 --start-cursor <cursor>\n\nBlock Commands\n# Retrieve a block\nvibe-notionbot block get <block_id>\n\n# List direct children of a block (paginated)\nvibe-notionbot block children <block_id>\nvibe-notionbot block children <block_id> --page-size 50 --start-cursor <cursor>\n\n# Append child blocks to a parent\nvibe-notionbot block append <parent_id> --content '[{\"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Hello World\"}}]}}]'\n\n# Append markdown content as blocks\nvibe-notionbot block append <parent_id> --markdown '# Hello\\n\\nThis is **bold** text.'\n\n# Append markdown from a file\nvibe-notionbot block append <parent_id> --markdown-file ./content.md\n\n# Append markdown with local images (auto-uploaded to Notion)\nvibe-notionbot block append <parent_id> --markdown-file ./doc-with-images.md\n\n# Append nested markdown (indented lists become nested children blocks)\nvibe-notionbot block append <parent_id> --markdown '- Parent item\\n  - Child item\\n    - Grandchild item'\n\n# Append blocks after a specific block (positional insertion)\nvibe-notionbot block append <parent_id> --after <block_id> --markdown '# Inserted after specific block'\nvibe-notionbot block append <parent_id> --after <block_id> --content '[{\"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Inserted after\"}}]}}]'\n\n# Append blocks before a specific block\nvibe-notionbot block append <parent_id> --before <block_id> --markdown '# Inserted before specific block'\n\n# Update a block's content\nvibe-notionbot block update <block_id> --content '{\"paragraph\": {\"rich_text\": [{\"type\": \"text\", \"text\": {\"content\": \"Updated content\"}}]}}'\n\n# Delete (archive) a block\nvibe-notionbot block delete <block_id>\n\n# Upload a file as a block (image or file block)\nvibe-notionbot block upload <parent_id> --file ./image.png --pretty\nvibe-notionbot block upload <parent_id> --file ./document.pdf --pretty\nvibe-notionbot block upload <parent_id> --file ./image.png --after <block_id> --pretty\nvibe-notionbot block upload <parent_id> --file ./image.png --before <block_id> --pretty\n\nUser Commands\n# List all users in the workspace\nvibe-notionbot user list\nvibe-notionbot user list --page-size 10 --start-cursor <cursor>\n\n# Get info for a specific user\nvibe-notionbot user get <user_id>\n\n# Get info for the current bot/integration\nvibe-notionbot user me\n\nSearch Commands\n# Search across the entire workspace\nvibe-notionbot search \"query text\"\n\n# Filter search by object type\nvibe-notionbot search \"Project\" --filter page\nvibe-notionbot search \"Tasks\" --filter database\n\n# Sort search results\nvibe-notionbot search \"Meeting\" --sort desc\n\n# Paginate search results\nvibe-notionbot search \"Notes\" --page-size 10 --start-cursor <cursor>\n\nComment Commands\n# List comments on a page\nvibe-notionbot comment list --page <page_id>\nvibe-notionbot comment list --page <page_id> --page-size 10 --start-cursor <cursor>\n\n# List inline comments on a specific block\nvibe-notionbot comment list --block <block_id>\n\n# Create a comment on a page\nvibe-notionbot comment create \"This is a comment\" --page <page_id>\n\n# Reply to a comment thread (discussion)\nvibe-notionbot comment create \"Replying to thread\" --discussion <discussion_id>\n\n# Retrieve a specific comment\nvibe-notionbot comment get <comment_id>\n\nBatch Operations\n\nRun multiple write operations in a single CLI call. Use this instead of calling the CLI repeatedly when you need to create, update, or delete multiple things at once. Saves tokens and reduces round-trips.\n\n# Inline JSON (no --workspace-id needed, uses NOTION_TOKEN)\nvibe-notionbot batch '<operations_json>'\n\n# From file (for large payloads)\nvibe-notionbot batch --file ./operations.json '[]'\n\n\nSupported actions (11 total):\n\nAction\tDescription\npage.create\tCreate a page\npage.update\tUpdate page properties\npage.archive\tArchive a page\nblock.append\tAppend blocks to a parent\nblock.update\tUpdate a block\nblock.delete\tDelete a block\ncomment.create\tCreate a comment\ndatabase.create\tCreate a database\ndatabase.update\tUpdate database title or schema\ndatabase.delete-property\tDelete a database property\nblock.upload\tUpload a file as an image or file block\n\nOperation format: Each operation is an object with action plus the same fields you'd pass to the individual command handler. Example with mixed actions:\n\n[\n  {\"action\": \"page.create\", \"parent\": \"<parent_id>\", \"title\": \"Meeting Notes\"},\n  {\"action\": \"block.append\", \"parent_id\": \"<page_id>\", \"markdown\": \"# Agenda\\n\\n- Item 1\\n- Item 2\"},\n  {\"action\": \"comment.create\", \"content\": \"Page created via batch\", \"page\": \"<page_id>\"}\n]\n\n\nOutput format:\n\n{\n  \"results\": [\n    {\"index\": 0, \"action\": \"page.create\", \"success\": true, \"data\": {\"id\": \"page-uuid\", \"...\": \"...\"}},\n    {\"index\": 1, \"action\": \"block.append\", \"success\": true, \"data\": {\"...\": \"...\"}},\n    {\"index\": 2, \"action\": \"comment.create\", \"success\": true, \"data\": {\"id\": \"comment-uuid\", \"...\": \"...\"}}\n  ],\n  \"total\": 3,\n  \"succeeded\": 3,\n  \"failed\": 0\n}\n\n\nFail-fast behavior: Operations run sequentially. If any operation fails, execution stops immediately. The output will contain results for all completed operations plus the failed one. The process exits with code 1 on failure, 0 on success.\n\n{\n  \"results\": [\n    {\"index\": 0, \"action\": \"page.create\", \"success\": true, \"data\": {\"...\": \"...\"}},\n    {\"index\": 1, \"action\": \"block.append\", \"success\": false, \"error\": \"Block not found\"}\n  ],\n  \"total\": 3,\n  \"succeeded\": 1,\n  \"failed\": 1\n}\n\nBulk Operations Strategy\n\nFor large operations (tens or hundreds of items), use --file to avoid shell argument limits and keep things manageable.\n\nStep 1: Write the operations JSON to a file, then run batch with --file:\n\n# Write operations to a file (using your Write tool), then:\nvibe-notionbot batch --file ./operations.json '[]'\n\n\nMulti-pass pattern — when new items need to reference each other (e.g., a page property linking to another newly created page):\n\nPass 1 — Create all items (without cross-references): Write a batch JSON file with all create operations, omitting properties that point to other new items. Run it. Collect the returned IDs from the output.\nPass 2 — Set cross-references: Write a second batch JSON file with update operations that set the referencing properties using the IDs from Pass 1. Run it.\nPass 1: Create items A, B, C (no cross-refs) → get IDs for A, B, C\nPass 2: Update A.related=B, C.parent_ref=A (using real IDs from Pass 1)\n\n\nThis is the same result as a script, but without writing any code. Just two batch calls.\n\nRate Limits\n\nNotion enforces rate limits on its API. Batch operations run sequentially, so a large batch (30+ operations) can trigger 429 Too Many Requests errors. To avoid this:\n\nSplit large batches into chunks of ~25-30 operations per batch call If a batch fails mid-way with a 429, re-run with only the remaining (unprocessed) operations The batch output shows which operations succeeded before the failure — use the index field to determine where to resume\n\nOutput Format\nJSON (Default)\n\nAll commands output JSON by default for AI consumption:\n\n{\n  \"id\": \"...\",\n  \"object\": \"page\",\n  \"properties\": { ... }\n}\n\nPretty (Human-Readable)\n\nUse --pretty flag for formatted output:\n\nvibe-notionbot search \"Project\" --pretty\n\nError Handling\n\nCommon errors from the Notion API:\n\nobject_not_found: The ID is incorrect or the integration doesn't have access.\nunauthorized: The NOTION_TOKEN is invalid.\nrate_limited: Too many requests.\nTroubleshooting\nvibe-notionbot: command not found\n\nThe vibe-notion package is not installed. Run it directly using a package runner. Ask the user which one to use:\n\nnpx -y -p vibe-notion vibe-notionbot ...\nbunx -p vibe-notion vibe-notionbot ...\npnpm dlx --package vibe-notion vibe-notionbot ...\n\n\nIf you already know the user's preferred package runner, use it directly instead of asking.\n\nLimitations\nSupports Notion API version 2025-09-03.\nDoes not support OAuth (token only).\nFile uploads are supported via block upload.\nPage property updates are limited to simple key=value pairs via --set."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/devxoul/vibe-notionbot",
    "publisherUrl": "https://clawhub.ai/devxoul/vibe-notionbot",
    "owner": "devxoul",
    "version": "1.2.2",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/vibe-notionbot",
    "downloadUrl": "https://openagent3.xyz/downloads/vibe-notionbot",
    "agentUrl": "https://openagent3.xyz/skills/vibe-notionbot/agent",
    "manifestUrl": "https://openagent3.xyz/skills/vibe-notionbot/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/vibe-notionbot/agent.md"
  }
}