Notion Agent Cli

CLI

node ${CLAUDE_PLUGIN_ROOT}/scripts/actions.mjs  [args...]

Run actions directly. If the decision tree does not cover your case, run schema for live metadata. Prefer schema over reading source.

Quick Patterns

• Read + summarize/report -> getPage -> createPage (2 calls)
• Copy with modifications -> copyPageWith (1 call)
• Merge pages -> createPage -> mergePages (2 calls)
• Batch property update -> batchSetProperties (1 call)

Decision Tree

• Find something -> search "query" or workspaceMap
• Read a page -> getPage
• Query a database -> queryDatabase (markdown table; --format raw for JSON)
• Create a page -> createPage "Title" "markdown content"
• Replace all content -> updatePage "content"
• Add to end -> appendBlocks "content"
• Update properties -> setProperties '{"Status":"Done"}'
• Markdown table to database -> importTable "| md | table |" --title "Name" (infers column types)
• Full copy with subpages -> deepCopy
• Copy + modify -> copyPageWith "Title" --appendMd "## Extra"
• Merge pages -> mergePages '["id1","id2"]'
• Read one section -> extractSection "Heading"
• Edit one section -> replaceSection "Heading" "new content"
• Batch update -> batchSetProperties '["id1","id2"]' '{"Status":"Done"}'

Key Behaviors

• Page reads and database queries return markdown by default.

getPage and extractSection return markdown. queryDatabase returns a compact markdown table with row IDs for follow-up actions.

• setProperties auto-types values from the database schema.

Pass {"Status": "Done"} — no raw Notion API format needed.

• createPage accepts markdown as the content argument.
• Compound actions save turns — each CLI call is one agentic turn:
• copyPageWith = read + modify + create in 1 call
• mergePages = N reads + merge in 1 call (target must exist; use createPage first)
• batchSetProperties = N updates in 1 call
• Stdin mode for large content:

echo '{"action":"createPage",...}' | node ${CLAUDE_PLUGIN_ROOT}/scripts/actions.mjs -

• Auto-snapshot before destructive operations.

Common Pitfalls

1. Do NOT fetch database entries individually — queryDatabase returns all in one call
2. Do NOT use getPage + createPage when copyPageWith does both in one call
3. Do NOT use multiple setProperties when batchSetProperties handles N pages
4. Do NOT read the script source — use schema or the references below
5. mergePages target must already exist — use createPage first to create it
6. Large content (>4KB) should use stdin mode, not inline CLI args
7. Properties are auto-typed from the database schema — pass simple values like {"Status": "Done"}, not raw Notion API format
8. File/image URLs expire after ~1 hour — re-fetch if reusing later

References

• references/action-reference.md — Read when you need exact parameter names or options for an unfamiliar action.
• references/workflows.md — Read when combining operations or piping large content via stdin.
• references/api-limits.md — Read when hitting API errors, size limits, or unexpected behavior.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jgorostegui
• Source: jgorostegui/notion-agent-cli
• License: MIT

Install and usage instructions live in the source repository linked above.