@andrzejchm/notion-cli 0.1.1 → 0.2.0

package/README.md

@@ -1,18 +1,23 @@
 # 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
+# Homebrew (recommended)
+brew tap andrzejchm/notion-cli
+brew install notion-cli
+
+# npm (alternative)
 npm install -g @andrzejchm/notion-cli
+
 notion init   # paste your Notion integration token once
 ```
 
----
-
 ## For AI Agents
 
 ```
@@ -21,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
@@ -45,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
@@ -67,6 +89,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 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 profile list\|use\|remove` | Manage multiple auth profiles |
 | `notion completion bash\|zsh\|fish` | Install shell tab completion |
 
@@ -96,6 +121,12 @@ The CLI auto-detects your context:
 
 ## Authentication
 
+Two authentication methods are available. If both are configured, **OAuth takes precedence** for API calls.
+
+### Internal integration token
+
+Run `notion init`. Suitable for read-only operations and automated agents. Write operations are attributed to the **integration bot** (not a real user).
+
 ```bash
 # Interactive setup (recommended for first-time use)
 notion init
@@ -112,6 +143,31 @@ notion profile use <name>
 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)
 
+### OAuth user login (recommended for write operations)
+
+Run `notion auth login`. Notion opens in your browser. After approving, your comments and pages will be attributed to your **actual Notion account** — not the integration bot.
+
+```bash
+notion auth login       # Opens browser, authenticates
+notion comment <id> -m "My comment"  # Now attributed to your user
+notion auth status      # Check auth state
+notion auth logout      # Remove OAuth session
+```
+
+**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.
+
+### 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
@@ -124,8 +180,12 @@ Get a token: [notion.so/profile/integrations/internal](https://www.notion.so/pro
 
 **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)