@andrzejchm/notion-cli 0.1.0

package/docs/agent-skill.md

@@ -0,0 +1,475 @@
+# Notion CLI — Agent Skill Reference
+
+> **Audience:** AI coding agents (Claude Code, OpenCode, Codex) and developers.
+> Use this reference to query Notion pages and databases directly from the terminal or within automated workflows.
+
+The `notion` CLI provides read access to Notion workspaces via the official API. Agents can fetch page content as markdown, query structured databases as JSON, and discover workspace resources — all without leaving the shell.
+
+---
+
+## Table of Contents
+
+1. [Installation & Setup](#installation--setup)
+2. [Agent Setup by Platform](#agent-setup-by-platform)
+3. [Output Modes](#output-modes)
+4. [Command Reference](#command-reference)
+   - [Authentication](#authentication)
+   - [Search & Discovery](#search--discovery)
+   - [Page Reading](#page-reading)
+   - [Database Operations](#database-operations)
+5. [Common Agent Patterns](#common-agent-patterns)
+6. [ID and URL Formats](#id-and-url-formats)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation & Setup
+
+```bash
+npm install -g @andrzejchm/notion-cli
+notion init   # interactive setup — enter your Notion integration token
+```
+
+**Alternative: environment variable (preferred for CI and agent environments)**
+
+```bash
+export NOTION_API_TOKEN=ntn_your_token_here
+```
+
+Get your token at: https://www.notion.so/profile/integrations/internal
+
+> **Integration access:** Each page or database your agent needs must be explicitly shared with your integration.
+> In Notion: open the page → `⋯` menu → **Add connections** → select your integration.
+
+---
+
+## Agent Setup by Platform
+
+### Claude Code
+
+Add to `CLAUDE.md`:
+
+```markdown
+## Notion Access
+
+Use `notion` CLI to access Notion pages and databases.
+
+- Auth: ensure `NOTION_API_TOKEN` is set, or run `notion init` once.
+- Page content: `notion read <id>` outputs markdown; pipe for JSON.
+- Structured data: `notion db query <id> --json | jq '.[] | .properties'`
+- See `docs/agent-skill.md` for full command reference and patterns.
+```
+
+### OpenCode
+
+Add to `.opencode/config.json`:
+
+```json
+{
+  "tools": ["bash"],
+  "instructions": "notion CLI is available for Notion access. See docs/agent-skill.md for full usage."
+}
+```
+
+Ensure `NOTION_API_TOKEN` is set in your shell environment before starting OpenCode.
+
+### Codex / Generic Agents
+
+Add to system prompt or `AGENTS.md`:
+
+```markdown
+Available tool: `notion` CLI (npm install -g @andrzejchm/notion-cli)
+Auth: set NOTION_API_TOKEN env var, or run `notion init` interactively.
+See docs/agent-skill.md for commands, flags, and agent patterns.
+```
+
+---
+
+## Output Modes
+
+The CLI auto-detects context and adjusts output format:
+
+| Context           | Default Output              | Override flag      |
+|-------------------|-----------------------------|--------------------|
+| Terminal (TTY)    | Formatted tables, colored   | `--json` for JSON  |
+| Piped / agent     | JSON                        | `--md` for markdown|
+
+**For agents: pipe the command to get JSON automatically:**
+
+```bash
+notion search "my query" | jq '.[]'
+notion ls | jq '.[] | {id, title}'
+notion db query "$DB_ID" | jq '.[] | .properties.Status'
+```
+
+**For page content: markdown is always the default in both modes:**
+
+```bash
+notion read "$PAGE_ID"          # markdown output (works in terminal AND piped)
+notion read "$PAGE_ID" --json   # raw JSON block tree
+```
+
+**Global flags** (apply to all commands):
+
+| Flag     | Effect                                 |
+|----------|----------------------------------------|
+| `--json` | Force JSON output (overrides TTY mode) |
+| `--md`   | Force markdown output                  |
+
+---
+
+## Command Reference
+
+### Authentication
+
+#### `notion init`
+
+Interactive setup wizard. Prompts for a profile name and integration token, validates the token against the Notion API, and saves the profile.
+
+```bash
+notion init
+```
+
+- Must be run in a TTY (terminal). Use `NOTION_API_TOKEN` env var in non-interactive environments.
+- On success: saves profile to `~/.notion.yaml` and sets it as active.
+
+---
+
+#### `notion profile list`
+
+Lists all saved auth profiles with the active profile marked.
+
+```bash
+notion profile list
+```
+
+```bash
+notion profile list --json
+# [{"name":"default","workspace":"My Workspace","active":true}, ...]
+```
+
+---
+
+#### `notion profile use <name>`
+
+Switches the active profile.
+
+```bash
+notion profile use work
+```
+
+---
+
+#### `notion profile remove <name>`
+
+Removes a saved profile. If the removed profile was active, no profile is set as active.
+
+```bash
+notion profile remove old-profile
+```
+
+---
+
+### Search & Discovery
+
+#### `notion search <query>`
+
+Searches workspace titles (not full-text content). Returns pages and databases accessible to your integration.
+
+```bash
+notion search "Meeting Notes"
+notion search "project docs" --type page
+notion search "tracker" --type database
+```
+
+**Flags:**
+
+| Flag              | Description                              |
+|-------------------|------------------------------------------|
+| `--type page`     | Return only pages                        |
+| `--type database` | Return only databases                    |
+| `--json`          | Force JSON output                        |
+
+**Agent usage:**
+
+```bash
+notion search "Weekly Review" --type page | jq '.[0].id'
+notion search "Tasks" --type database --json | jq '.[0].id'
+```
+
+**JSON output shape:**
+
+```json
+[
+  {
+    "id": "abc123def456789012345678901234ab",
+    "title": "Weekly Review",
+    "type": "page",
+    "url": "https://www.notion.so/myworkspace/Weekly-Review-abc123"
+  }
+]
+```
+
+---
+
+#### `notion ls`
+
+Lists all top-level pages and databases shared with your integration.
+
+```bash
+notion ls
+notion ls --json
+```
+
+**Agent usage:**
+
+```bash
+notion ls | jq '.[] | select(.type == "database") | {id, title}'
+```
+
+---
+
+#### `notion open <id/url>`
+
+Opens a Notion page or database in the default browser. Prints the URL to stdout for scriptable use.
+
+```bash
+notion open abc123def456789012345678901234ab
+notion open "https://www.notion.so/myworkspace/My-Page-abc123"
+```
+
+---
+
+#### `notion users`
+
+Lists all members of the workspace.
+
+```bash
+notion users
+notion users --json
+```
+
+**JSON output shape:**
+
+```json
+[
+  {
+    "id": "user-uuid",
+    "name": "Alice Smith",
+    "email": "alice@example.com",
+    "type": "person"
+  }
+]
+```
+
+---
+
+#### `notion comments <id/url>`
+
+Lists all comments on a page.
+
+```bash
+notion comments abc123def456789012345678901234ab
+notion comments "https://www.notion.so/myworkspace/My-Page-abc123" --json
+```
+
+**JSON output shape:**
+
+```json
+[
+  {
+    "id": "comment-uuid",
+    "author": "Alice Smith",
+    "text": "This looks good!",
+    "created": "2026-01-15T10:00:00Z"
+  }
+]
+```
+
+---
+
+### Page Reading
+
+#### `notion read <id/url>`
+
+Fetches a Notion page and outputs its content as markdown. This is the primary command for reading page content.
+
+```bash
+notion read abc123def456789012345678901234ab
+notion read "https://www.notion.so/myworkspace/My-Page-abc123def456"
+notion read abc123def456789012345678901234ab --json   # raw JSON block tree
+```
+
+**Flags:**
+
+| Flag     | Description                      |
+|----------|----------------------------------|
+| `--json` | Output raw Notion JSON block tree |
+
+**Notes:**
+- Default output is always markdown (even when piped).
+- Accepts 32-char hex IDs, UUID format, or full Notion URLs.
+- The page must be shared with your integration.
+
+**Agent usage:**
+
+```bash
+# Read and search for a section
+notion read "$PAGE_ID" | grep -A 10 "## Action Items"
+
+# Extract all headings
+notion read "$PAGE_ID" | grep "^#"
+
+# Pass to LLM for summarization
+notion read "$PAGE_ID" | your-summarize-command
+```
+
+---
+
+### Database Operations
+
+#### `notion db schema <id/url>`
+
+Retrieves the schema (property names and types) of a Notion database. **Always run this before building filters** to see available properties and valid select/status values.
+
+```bash
+notion db schema abc123def456789012345678901234ab
+notion db schema "$DB_ID" --json
+```
+
+**JSON output shape:**
+
+```json
+{
+  "id": "abc123def456789012345678901234ab",
+  "title": "Project Tracker",
+  "properties": {
+    "Name": { "type": "title" },
+    "Status": {
+      "type": "select",
+      "options": ["Not started", "In Progress", "Done"]
+    },
+    "Assignee": { "type": "people" },
+    "Due Date": { "type": "date" }
+  }
+}
+```
+
+---
+
+#### `notion db query <id/url>`
+
+Queries a Notion database with optional filters, sorting, and column selection.
+
+```bash
+notion db query abc123def456789012345678901234ab
+notion db query "$DB_ID" --filter "Status=Done"
+notion db query "$DB_ID" --filter "Priority=High" --filter "Status=In Progress"
+notion db query "$DB_ID" --sort "Name:asc"
+notion db query "$DB_ID" --sort "Created:desc"
+notion db query "$DB_ID" --columns "Title,Status,Assignee"
+notion db query "$DB_ID" --json
+```
+
+**Flags:**
+
+| Flag                   | Description                                                    |
+|------------------------|----------------------------------------------------------------|
+| `--filter "Prop=Val"`  | Filter rows where property equals value. Repeatable.           |
+| `--sort "Prop:dir"`    | Sort by property. Direction: `asc` or `desc`. Repeatable.      |
+| `--columns "A,B,C"`    | Limit output to specific columns (comma-separated).            |
+| `--json`               | Force JSON output.                                             |
+
+**Agent usage:**
+
+```bash
+# Get all done items as JSON
+notion db query "$DB_ID" --filter "Status=Done" --json | jq '.[] | .properties'
+
+# Extract title and status for each row
+notion db query "$DB_ID" --json | jq '.[] | {id, title: .properties.Name, status: .properties.Status}'
+
+# Get most recently modified items
+notion db query "$DB_ID" --sort "Last edited:desc" --columns "Title,Status" | head -20
+```
+
+**JSON output shape:**
+
+```json
+[
+  {
+    "id": "row-uuid",
+    "properties": {
+      "Name": "Project Alpha",
+      "Status": "In Progress",
+      "Assignee": "Alice Smith",
+      "Due Date": "2026-03-01"
+    }
+  }
+]
+```
+
+---
+
+## Common Agent Patterns
+
+```bash
+# Pattern 1: Find a page by title, then read it
+PAGE_ID=$(notion search "Meeting Notes" --type page | jq -r '.[0].id')
+notion read "$PAGE_ID"
+
+# Pattern 2: Get all items with a specific status from a database
+DB_ID=$(notion search "Project Tracker" --type database | jq -r '.[0].id')
+notion db query "$DB_ID" --filter "Status=Done" | jq '.[] | .properties'
+
+# Pattern 3: List recent entries sorted by date
+notion db query "$DB_ID" --sort "Last edited:desc" --columns "Title,Status" | head -20
+
+# Pattern 4: Read a page and extract specific content
+notion read "$PAGE_ID" | grep -A 5 "## Action Items"
+
+# Pattern 5: Check database schema before building a filter
+notion db schema "$DB_ID"   # see what properties exist and their valid values
+notion db query "$DB_ID" --filter "Status=In Progress"
+
+# Pattern 6: Using URLs instead of IDs
+notion read "https://www.notion.so/myworkspace/My-Page-abc123def456"
+notion db query "https://www.notion.so/myworkspace/My-DB-abc123def456"
+
+# Pattern 7: Combine search + query in one pipeline
+notion search "Tasks" --type database | jq -r '.[0].id' | xargs -I{} notion db query {} --filter "Assignee=Alice" --json
+```
+
+---
+
+## ID and URL Formats
+
+The CLI accepts any of these formats for the `<id>` argument in all commands:
+
+| Format       | Example                                              |
+|--------------|------------------------------------------------------|
+| 32-char hex  | `abc123def456789012345678901234ab`                   |
+| UUID         | `abc123de-f456-7890-1234-5678901234ab`               |
+| Full URL     | `https://www.notion.so/workspace/Page-Title-abc123`  |
+
+All commands (`read`, `db query`, `db schema`, `open`, `comments`) accept any of these formats.
+
+---
+
+## Troubleshooting
+
+**Page not found (404):** The page must be shared with your integration.
+In Notion: open the page → `⋯` menu → **Add connections** → select your integration.
+
+**Unauthorized (401):** Your token is invalid or expired.
+Run `notion init` to reconfigure, or set a new `NOTION_API_TOKEN`.
+Get a new token at: https://www.notion.so/profile/integrations/internal
+
+**Search returns no results:** Search is title-only (not full-text content search).
+The page or database must also be explicitly shared with your integration.
+
+**Empty database query:** No entries match your filters, or the database has no entries.
+Run `notion db schema <id>` first to see available properties and their valid values.
+
+**`notion init` fails in agent/CI environment:** `notion init` requires an interactive terminal (TTY).
+Use the `NOTION_API_TOKEN` environment variable instead.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@andrzejchm/notion-cli",
+  "version": "0.1.0",
+  "description": "Read Notion pages and databases from the terminal. Built for AI agents and developers.",
+  "keywords": ["notion", "cli", "notion-api", "ai-agent", "markdown", "database"],
+  "author": "Andrzej Chm",
+  "license": "MIT",
+  "homepage": "https://github.com/andrzejchm/notion-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andrzejchm/notion-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/andrzejchm/notion-cli/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist/",
+    "docs/agent-skill.md",
+    "README.md"
+  ],
+  "type": "module",
+  "bin": {
+    "notion": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "@notionhq/client": "^5.10.0",
+    "chalk": "^5.6.0",
+    "commander": "^14.0.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@commander-js/extra-typings": "^14.0.0",
+    "@types/node": "^22",
+    "tsup": "^8.5.0",
+    "typescript": "~5.9.0",
+    "vitest": "^4.0.0"
+  }
+}