@andrzejchm/notion-cli 0.1.2 → 0.3.0

package/docs/README.agents.md

@@ -0,0 +1,81 @@
+# 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.agents.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
+
+**Interactive setup** (choose OAuth or integration token):
+```bash
+notion auth login
+```
+
+**Integration token only** (CI/agents — no TTY needed):
+```bash
+export NOTION_API_TOKEN=ntn_your_token_here
+```
+
+Get a token: https://www.notion.so/profile/integrations/internal
+
+**OAuth** (recommended for write operations — attributes comments/pages to your user):
+```bash
+notion auth login          # select "OAuth user login" in the prompt
+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,176 @@
+---
+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 auth login   # interactive setup — choose OAuth or 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**.
+
+| Method | Command | Attribution | Notes |
+|--------|---------|-------------|-------|
+| Interactive setup | `notion auth login` | — | Guides you to choose; TTY required |
+| OAuth user login | select "OAuth user login" in `notion auth login` | Your Notion account | Browser required; `--manual` for headless |
+| Integration token | select "Integration token" in `notion auth login` | Integration bot | Works in CI/headless; must connect integration to pages |
+
+```bash
+notion auth login                    # interactive selector — OAuth or integration token
+notion auth login --manual           # headless OAuth (prints URL, paste redirect back)
+notion auth status                   # show current auth state
+notion auth logout                   # remove a profile (interactive selector)
+notion auth logout --profile <name>  # remove specific profile directly
+notion auth list                     # list all saved profiles
+notion auth use <name>               # switch active profile
+```
+
+**Headless/CI agents:** Use `NOTION_API_TOKEN=<token>` env var — overrides all config, no TTY needed.
+
+---
+
+## 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
+```
+
+---
+
+## 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 auth login` 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 auth login` requires TTY** — Use `NOTION_API_TOKEN` env var in agents, or use `notion auth login --manual` for headless OAuth.
+
+**`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.3.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",
@@ -36,7 +36,14 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format .",
+    "format:write": "biome format --write .",
+    "check": "biome check .",
+    "check:write": "biome check --write .",
+    "ci": "npm run typecheck && npm run check"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
@@ -46,6 +53,7 @@
     "yaml": "^2.8.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
     "@commander-js/extra-typings": "^14.0.0",
     "@types/node": "^22",
     "tsup": "^8.5.0",