@andrzejchm/notion-cli 0.1.2 → 0.2.0

package/docs/README.agents.md

@@ -0,0 +1,77 @@
+# notion-cli for OpenCode
+
+Complete guide for using notion-cli with [OpenCode](https://opencode.ai).
+
+## Quick Install
+
+Tell OpenCode:
+
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/README.opencode.md
+```
+
+## Installation
+
+### 1. Install the CLI
+
+```bash
+# Homebrew (recommended)
+brew tap andrzejchm/notion-cli
+brew install notion-cli
+
+# npm (alternative)
+npm install -g @andrzejchm/notion-cli
+```
+
+Homebrew bundles Node.js automatically. npm requires Node.js ≥ 22.
+
+### 2. Install the skill file
+
+```bash
+mkdir -p ~/.config/opencode/skills/using-notion-cli
+curl -fsSL https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/skills/using-notion-cli/SKILL.md \
+  -o ~/.config/opencode/skills/using-notion-cli/SKILL.md
+```
+
+### 3. Authenticate
+
+**Internal integration token** (read-only and automated agents):
+```bash
+notion init
+# or: export NOTION_API_TOKEN=ntn_your_token_here
+```
+
+Get a token: https://www.notion.so/profile/integrations/internal
+
+**OAuth login** (recommended for write operations — attributes comments/pages to your user):
+```bash
+notion auth login          # opens browser
+notion auth login --manual # headless: prints URL, paste redirect back
+```
+
+### 4. Share pages with your integration
+
+Open any Notion page → `⋯` → **Add connections** → select your integration.
+
+### 5. Verify
+
+```bash
+notion --version   # CLI installed
+notion ls          # auth works
+```
+
+Restart OpenCode after installing. The skill is now discoverable via the `skill` tool.
+
+## Updating
+
+```bash
+# Homebrew
+brew upgrade notion-cli
+
+# npm
+npm install -g @andrzejchm/notion-cli
+
+# Update skill file (either install method)
+curl -fsSL https://raw.githubusercontent.com/andrzejchm/notion-cli/main/docs/skills/using-notion-cli/SKILL.md \
+  -o ~/.config/opencode/skills/using-notion-cli/SKILL.md
+```

package/docs/demo.tape

@@ -0,0 +1,26 @@
+Output demo.gif
+
+Set FontSize 14
+Set Width 800
+Set Height 400
+Set Theme "Dracula"
+Set Padding 20
+Set TypingSpeed 40ms
+Env PATH "/Users/andrzejchm/.nvm/versions/node/v24.13.0/bin:/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
+
+Sleep 500ms
+
+Type "notion search demo"
+Sleep 500ms
+Enter
+Sleep 3s
+
+Type "notion read 314e707e00688087b2eef0af1de30033"
+Sleep 500ms
+Enter
+Sleep 4s
+
+Type "notion db schema 314e707e-0068-8035-8e42-000b2f2ded85"
+Sleep 500ms
+Enter
+Sleep 3s

package/docs/skills/using-notion-cli/SKILL.md

@@ -0,0 +1,186 @@
+---
+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.
+license: MIT
+compatibility: opencode
+---
+
+## Setup
+
+Install once:
+```bash
+npm install -g @andrzejchm/notion-cli
+notion init   # enter your Notion integration token
+```
+
+Or set env var (preferred for CI/agents):
+```bash
+export NOTION_API_TOKEN=ntn_your_token_here
+```
+
+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 create-page`: also need **Insert content**
+- `notion comment`: also need **Read comments** + **Insert comments**
+
+---
+
+## Authentication
+
+Two auth methods are available. If both are configured, **OAuth takes precedence**.
+
+### Internal integration token (default)
+Set up via `notion init`. Comments and pages created via this method are attributed to the **integration bot** (not a real user).
+
+```bash
+notion init                    # interactive setup (requires TTY)
+export NOTION_API_TOKEN=ntn_…  # or via environment variable
+```
+
+### OAuth user login (recommended for write operations)
+Set up via `notion auth login`. Comments and pages are attributed to your **actual Notion user account**.
+
+```bash
+notion auth login [--profile <name>] [--manual]   # opens browser OAuth flow; --manual for headless
+notion auth logout [--profile <name>]              # removes OAuth tokens
+notion auth status [--profile <name>]              # shows current auth state
+```
+
+**Headless / remote servers:** `notion auth login --manual` prints the auth URL for you to open in a local browser, then prompts you to paste the redirect URL back.
+
+---
+
+## Output Modes
+
+| 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")'
+```
+
+---
+
+## Commands
+
+### Search & Discovery
+
+```bash
+notion search "query"                    # search all pages/databases by title
+notion search "query" --type page        # pages only
+notion search "query" --type database    # databases only
+notion ls                                # list everything accessible to integration
+notion users                             # list workspace members
+notion comments <id|url>                 # list page comments
+notion open <id|url>                     # open in browser
+```
+
+### Reading Pages
+
+```bash
+notion read <id|url>          # markdown (always, even when piped)
+notion read <id|url> --json   # raw Notion JSON block tree
+```
+
+### Database Operations
+
+```bash
+notion db schema <id|url>                             # inspect properties + valid values
+notion db query <id|url>                              # all rows
+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'
+```
+
+### Write Operations
+
+```bash
+notion append <id|url> -m "## Heading\nParagraph text"   # append markdown blocks to a page
+notion append <id|url> -m "$(cat notes.md)"              # append file contents
+
+notion create-page --parent <id|url> --title "Title"               # title-only page
+notion create-page --parent <id|url> --title "Title" -m "# Hello"  # with markdown body
+echo "# Content" | notion create-page --parent <id|url> --title "Title"  # from stdin
+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
+```
+
+### Auth
+
+```bash
+notion init                   # interactive setup (requires TTY)
+notion profile list           # show saved profiles
+notion profile use <name>     # switch active profile
+notion profile remove <name>  # delete a profile
+```
+
+---
+
+## 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)
+
+---
+
+## Agent Patterns
+
+```bash
+# Find page by title, read it
+PAGE_ID=$(notion search "Meeting Notes" --type page | jq -r '.[0].id')
+notion read "$PAGE_ID"
+
+# Get database ID, then query with filter
+DB_ID=$(notion search "Project Tracker" --type database | jq -r '.[0].id')
+notion db query "$DB_ID" --filter "Status=In Progress" | jq '.[] | .properties'
+
+# Always check schema before filtering (see valid property names/values)
+notion db schema "$DB_ID"
+notion db query "$DB_ID" --filter "Status=Done"
+
+# Extract page section
+notion read "$PAGE_ID" | grep -A 10 "## Action Items"
+
+# Summarize a page and append the summary back
+SUMMARY=$(notion read "$PAGE_ID" | your-summarize-command)
+notion append "$PAGE_ID" -m "## AI Summary\n$SUMMARY"
+
+# Create a page and capture its URL for further use
+URL=$(notion create-page --parent "$PAGE_ID" --title "Report $(date +%Y-%m-%d)" -m "# Report\n...")
+echo "Created: $URL"
+
+# Pipe command output into a new page
+my-report-command | notion create-page --parent "$PAGE_ID" --title "Auto Report"
+```
+
+---
+
+## Troubleshooting
+
+**404 / page not found** — Share the page with your integration: page → `⋯` → **Add connections**.
+
+**401 / unauthorized** — Run `notion init` or set `NOTION_API_TOKEN`.
+
+**Search returns nothing** — Search is title-only. Page must be shared with integration.
+
+**Empty db query** — Run `notion db schema <id>` to see valid property names and values.
+
+**`notion init` fails in agent** — Requires TTY. Use `NOTION_API_TOKEN` env var instead.
+
+**`notion comment` returns "Insufficient permissions"** — Enable **Read comments** + **Insert comments** in integration capabilities: notion.so/profile/integrations/internal → your integration → Capabilities.
+
+**`notion append` / `notion create-page` returns "Insufficient permissions"** — Enable **Insert content** in integration capabilities.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrzejchm/notion-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Read Notion pages and databases from the terminal. Built for AI agents and developers.",
   "keywords": [
     "notion",
@@ -25,7 +25,7 @@
   },
   "files": [
     "dist/",
-    "docs/agent-skill.md",
+    "docs/",
     "README.md"
   ],
   "type": "module",