Notion

# 1. Token einmalig setzen (wird automatisch gefunden)
echo 'export NOTION_API_TOKEN=secret_xxx' >> ~/.zshrc

# 2. Build
cd ${CLAUDE_SKILL_DIR} && npm install && npm run build

# 3. Alias (optional)
alias notion='node ${CLAUDE_SKILL_DIR}/dist/scripts/notion.js'

CLI Usage

Read (Markdown Export)

notion read <page-id-or-url>
notion read <id> --children                    # Mit verschachtelten Blöcken
notion read <id> --download=./images           # Attachments herunterladen

Query Database

notion query <database-id-or-url>
notion query <id> --filter="Status=Done"
notion query <id> --format=json --limit=50

Search

notion search "Keyword"
notion search "Project" --filter=page
notion search "Tasks" --filter=database

Create

# Als Child-Page
notion create --parent=<page-id> --title="New Page"

# Als Database-Eintrag
notion create --database=<db-id> --props="Name=Task,Status=To Do,Priority=High"

Update

notion update <page-id> --props="Status=Done,Priority=Low"

Schema (Database-Struktur)

notion schema <database-id-or-url>
# Zeigt: Properties, Types, Select-Optionen, Formeln

Export (CSV)

notion export <database-id-or-url>
notion export <id> --output=mydata.csv

Rich Page Building (Block API)

For complex pages (columns, callouts, toggles, nested content), the CLI isn't enough. Use the Block API directly via Python or curl.

Full reference: references/block-building.md

Key capabilities:

• Column layouts (column_list) — side-by-side comparisons
• Callouts with emoji icons and colored backgrounds
• Toggles with nested children (collapsible content)
• Insert after specific blocks (surgical placement)
• Nested children in callouts/toggles (up to 2 levels)

Quick example — two-column comparison:

column_list(
    [callout("🔴", [rt("Concept A", bold=True)], "red_background"),
     bullet(rt("Property 1")), bullet(rt("Property 2"))],
    [callout("🟠", [rt("Concept B", bold=True)], "orange_background"),
     bullet(rt("Property 1")), bullet(rt("Property 2"))],
)

Workflow: Read page → scan block IDs → build blocks with helpers → PATCH append/insert

Library Usage

import { NotionClient } from "./lib/notion-client.js";

const client = new NotionClient({ token: process.env.NOTION_API_TOKEN });

// Page erstellen
const page = await client.createPage({
  parent: { database_id: "db-id" },
  properties: {
    Name: { title: [{ text: { content: "New Task" } }] },
    Status: { select: { name: "To Do" } },
  },
});

// Page updaten
await client.updatePage("page-id", {
  Status: { select: { name: "Done" } },
});

// File URL holen
const url = await client.getFileUrl("block-id");

IDs finden

Page/Database ID aus URL