notion-sync

Files (15)

• origin.json · .clawhub/
• SKILL.md
• _meta.json
• API-REFERENCE.md · references/
• add-to-database.js · scripts/
• batch-update.js · scripts/
• delete-notion-page.js · scripts/
• get-database-schema.js · scripts/
• md-to-notion.js · scripts/
• notion-to-md.js · scripts/
• notion-utils.js · scripts/
• query-database.js · scripts/
• search-notion.js · scripts/
• update-page-properties.js · scripts/
• watch-notion.js · scripts/

SKILL.md (first lines)

# Notion Sync

Bi-directional sync between markdown files and Notion pages, plus database management utilities for research tracking and project management.

## Upgrading

**From v2.0:** Replace `--token "ntn_..."` with `--token-file`, `--token-stdin`, or `NOTION_API_KEY` env var. Bare `--token` is no longer accepted (credentials should never appear in process listings).

**From v1.x:** See v2.0 changelog for migration details.

## Requirements

- **Node.js** v18 or later
- A **Notion integration token** (starts with `ntn_` or `secret_`)

## Setup

1. Go to https://www.notion.so/my-integrations
2. Create a new integration (or use an existing one)
3. Copy the "Internal Integration Token"
4. Pass the token using one of these methods (priority order used by scripts):

   **Option A — Token file (recommended):**
   ```bash
   echo "ntn_your_token" > ~/.notion-token && chmod 600 ~/.notion-token
   node scripts/search-notion.js "query" --token-file ~/.notion-token
   ```

   **Option B — Stdin pipe:**
   ```bash
   echo "$NOTION_API_KEY" | node scripts/search-notion.js "query" --token-stdin
   ```

   **Option C — Environment variable:**
   ```bash
   export NOTION_API_KEY="ntn_your_token"
   node scripts/search-notion.js "query"
   ```

   **Auto default:** If `~/.notion-token` exists, scripts use it automatically even without `--token-file`.

5. Share your Notion pages/databases with the integration:
   - Open the page/database in Notion
   - Click "Share" → "Invite"
   - Select your integration


## JSON Output Mode

All scripts support a global `--json` flag.

- Suppresses progress logs written to stderr
- Keeps stdout machine-readable for automation
- Errors are emitted as JSON: `{ "error": "..." }`

Example:
```bash
node scripts/query-database.js <db-id> --limit 5 --json
```

## Path Safety Mode

Scripts that read/write local files are restricted to the current working directory by default.

- Prevents accidental reads/writes outside the intended workspace
- Applies to: `md-to-notion.js`, `add-to-database.js`, `notion-to-md.js`, `watch-notion.js`
- Override intentionally with `--allow-unsafe-paths`

Examples:
```bash
# Default (safe): path must be inside current workspace
node scripts/md-to-notion.js docs/draft.md <parent-id> "Draft"

# Intentional override (outside workspace)
node scripts/notion-to-md.js <page-id> ~/Downloads/export.md --allow-unsafe-paths
```

## Core Operations

### 1. Search Pages and Databases

Search across your Notion workspace by title or content.

```bash
node scripts/search-notion.js "<query>" [--filter page|database] [--limit 10] [--json]
```

**Examples:**
```bash
# Search for newsletter-related pages
node scripts/search-notion.js "newsletter"

# Find only databases
node scripts/search-notion.js "research" --filter database

# Limit results
node scripts/search-notion.js "AI" --limit 5
```

**Output:**
```json
[
  {
    "id": "page-id-here",
    "object": "page",
    "title": "Newsletter Draft",
    "url": "https://notion.so/...",
    "lastEdited": "2026-02-01T09:00:00.000Z"
  }
]
```

### 2. Query Databases with Filters

Query database contents with advanced filters and sorting.

```bash
node scripts/query-database.js <database-id> [--filter <json>] [--sort <json>] [--limit 10] [--json]
```

From jordanjayhays-cpu/007-Axton, MIT-0.

More from jordanjayhays-cpu/007-Axton