@andrzejchm/notion-cli 0.1.2 → 0.3.0

package/README.md

@@ -1,19 +1,22 @@
 # notion-cli
 
-> Read Notion pages and databases from your terminal — built for AI coding agents and developers.
+> Read and write Notion pages from your terminal — built for AI coding agents and developers.
 
 [![npm version](https://img.shields.io/npm/v/@andrzejchm/notion-cli.svg?style=flat&color=4B78E6)](https://www.npmjs.com/package/@andrzejchm/notion-cli)
+[![homebrew tap](https://img.shields.io/badge/homebrew-andrzejchm%2Fnotion--cli-orange?style=flat&logo=homebrew)](https://github.com/andrzejchm/homebrew-notion-cli)
 [![Node.js >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen?style=flat)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
 
 ```bash
-npm install -g @andrzejchm/notion-cli
-notion init   # paste your Notion integration token once
-```
+# Homebrew (recommended)
+brew tap andrzejchm/notion-cli
+brew install notion-cli
 
-![notion-cli demo](docs/demo.gif)
+# npm (alternative)
+npm install -g @andrzejchm/notion-cli
 
----
+notion auth login   # choose your auth method
+```
 
 ## For AI Agents
 
@@ -23,11 +26,18 @@ Fetch and follow instructions from https://raw.githubusercontent.com/andrzejchm/
 
 ---
 
+![notion-cli demo](docs/demo.gif)
+
+---
+
 ## Features
 
 - **`notion search`** — find any page or database by title
 - **`notion read`** — render any page as full-fidelity markdown
 - **`notion db query`** — filter, sort, and select columns from any database
+- **`notion append`** — append markdown content to an existing page
+- **`notion create-page`** — create a new page with markdown body, prints URL to stdout
+- **`notion comment`** — add a comment to a page
 - **Agent-friendly** — plain text tables by default; `--json` for machine-readable output
 - **Flexible auth** — interactive setup or `NOTION_API_TOKEN` env var
 - **Accepts URLs** — pass full Notion URLs anywhere an ID is expected
@@ -47,8 +57,18 @@ notion db query "$DB_ID" --filter "Status=In Progress" --sort "Priority:asc"
 # Get JSON output for scripting / AI agents
 notion db query "$DB_ID" --filter "Status=Done" | jq '.[] | .properties.Title'
 
-# Inspect a database schema before querying
-notion db schema "$DB_ID"
+# Append markdown blocks to an existing page
+notion append "$PAGE_ID" -m "## Summary\nGenerated by AI agent."
+
+# Create a new page and capture its URL
+URL=$(notion create-page --parent "$PAGE_ID" --title "Meeting Notes" -m "# Agenda\n- Item 1")
+echo "Created: $URL"
+
+# Pipe content to a new page
+my-summarize-command | notion create-page --parent "$PAGE_ID" --title "Auto Summary"
+
+# Add a comment to a page
+notion comment "$PAGE_ID" -m "Reviewed and approved."
 
 # List everything your integration can access
 notion ls
@@ -60,7 +80,11 @@ notion ls
 
 | Command | Description |
 |---------|-------------|
-| `notion init` | Set up your Notion integration token |
+| `notion auth login` | Interactive auth setup — choose OAuth or integration token |
+| `notion auth logout` | Remove a profile and all its credentials |
+| `notion auth status` | Show current auth state |
+| `notion auth list` | List all saved profiles |
+| `notion auth use <name>` | Switch the active profile |
 | `notion search <query>` | Search pages and databases by title |
 | `notion ls` | List all accessible pages and databases |
 | `notion open <id\|url>` | Open a page in your browser |
@@ -69,7 +93,9 @@ notion ls
 | `notion db query <id\|url>` | Query database entries with filtering and sorting |
 | `notion users` | List workspace members |
 | `notion comments <id\|url>` | Read page comments |
-| `notion profile list\|use\|remove` | Manage multiple auth profiles |
+| `notion comment <id\|url> -m <text>` | Add a comment to a page |
+| `notion append <id\|url> -m <markdown>` | Append markdown blocks to a page |
+| `notion create-page --parent <id\|url> --title <title>` | Create a new page, prints URL |
 | `notion completion bash\|zsh\|fish` | Install shell tab completion |
 
 ### `notion db query` flags
@@ -98,36 +124,90 @@ The CLI auto-detects your context:
 
 ## Authentication
 
+Two authentication methods are available. If both are configured, **OAuth takes precedence** for API calls.
+
+Start with the interactive setup:
+
 ```bash
-# Interactive setup (recommended for first-time use)
-notion init
+notion auth login   # choose OAuth or integration token
+```
 
-# Environment variable (CI, Docker, agents)
-export NOTION_API_TOKEN=ntn_your_token_here
+### Tradeoff comparison
+
+| Method | Best for | Write attribution | Requires |
+|--------|----------|-------------------|----------|
+| **OAuth user login** | Write-heavy workflows, personal use | Your Notion account | Browser (or `--manual` for headless) |
+| **Integration token** | CI, Docker, automated agents | Integration bot | Token from notion.so/profile/integrations |
+| `NOTION_API_TOKEN` env var | CI/Docker without config files | Integration bot | Token set in environment |
+
+**Priority:** `NOTION_API_TOKEN` env var → OAuth token → integration token (first found wins)
+
+### OAuth user login
 
-# Multiple workspaces
-notion init                    # saves as "default"
-notion profile list
-notion profile use <name>
+```bash
+notion auth login         # interactive selector — choose OAuth
+notion auth login --manual  # headless: prints URL, prompts to paste redirect
+notion auth status        # show current auth state
+notion auth logout        # remove profile and credentials
+```
+
+Comments and pages are attributed to your **actual Notion account**.
+Access tokens expire after ~1 hour and are refreshed automatically.
+
+### Integration token
+
+```bash
+notion auth login   # interactive selector — choose "Integration token"
+
+# or: environment variable (CI, Docker, agents — no profile needed)
+export NOTION_API_TOKEN=ntn_your_token_here
 ```
 
+Works everywhere (CI, headless, agents). Write operations are attributed to the **integration bot**.
+You must manually connect the integration to each page (`⋯` → Add connections).
+
 Token format: starts with `ntn_` (new) or `secret_` (legacy integrations).  
 Get a token: [notion.so/profile/integrations/internal](https://www.notion.so/profile/integrations/internal)
 
+### Profile management
+
+```bash
+notion auth list          # list all profiles
+notion auth use <name>    # switch active profile
+notion auth logout        # remove a profile (interactive selector)
+notion auth logout --profile <name>  # remove specific profile directly
+```
+
+### Integration capabilities
+
+Read-only commands (`search`, `read`, `db query`, etc.) need **Read content** only.
+
+Write commands require additional capabilities — enable in your integration settings ([notion.so/profile/integrations/internal](https://www.notion.so/profile/integrations/internal) → your integration → **Capabilities**):
+
+| Command | Required capabilities |
+|---------|----------------------|
+| `notion append` | Read content, Insert content |
+| `notion create-page` | Read content, Insert content |
+| `notion comment` | Read content, Insert content, Read comments, Insert comments |
+
 ---
 
 ## Troubleshooting
 
 **Page not found (404):** Share the page with your integration — open the page → `⋯` → **Add connections**.
 
-**Unauthorized (401):** Run `notion init` to reconfigure, or check your `NOTION_API_TOKEN`.
+**Unauthorized (401):** Run `notion auth login` to reconfigure, or check your `NOTION_API_TOKEN`.
 
 **Search returns nothing:** Search is title-only. The page must also be shared with your integration.
 
 **Empty database query:** Run `notion db schema <id>` first to see valid property names and values.
 
+**`notion comment` returns "Insufficient permissions":** Enable **Read comments** and **Insert comments** in your integration capabilities: [notion.so/profile/integrations/internal](https://www.notion.so/profile/integrations/internal) → your integration → Capabilities.
+
+**`notion append` / `notion create-page` returns "Insufficient permissions":** Enable **Insert content** in your integration capabilities.
+
 ---
 
 ## License
 
-MIT © [Andrzej Chm](https://github.com/andrzejchm)
+MIT © [Andrzej Chmielewski](https://github.com/andrzejchm)