Introduction
# notion Use *notion-cli* to create/read/update pages, data sources (databases), and blocks. ## Setup - Install notion-cli: `npm install -g @iansinnott/notion-cli` - Create an integration at https://notion.so/my-integrations - Copy the API key (starts with *ntn_* or *secret_*) - Store it: - `mkdir -p ~/.config/notion` - `echo "ntn_your_key_here" > ~/.config/notion/api_key` - Share target pages/databases with your integration (click "..." → "Connect to" → your integration name) ## Usage All commands require the *NOTION_TOKEN* environment variable to be set: ```bash export NOTION_TOKEN=$(cat ~/.config/notion/api_key) ``` ## Common Operations - **Search for pages and data sources:** `notion-cli search --query "page title"` - **Get page:** `notion-cli page retrieve <PAGE_ID>` - **Get page content (blocks):** `notion-cli page retrieve <PAGE_ID> -r` - **Create page in a database:** ```bash curl -X POST https://api.notion.com/v1/pages \ -H "Authorization: Bearer $NOTION_TOKEN" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ --data '{ "parent": { "database_id": "YOUR_DATABASE_ID" }, "properties": { "Name": { "title": [ { "text": { "content": "Nouvelle idée" } } ] } } }' ``` - **Query a database:** `notion-cli db query <DB_ID> -a '{"property":"Status","status":{"equals":"Active"}}'` - **Update page properties:** ```bash curl -X PATCH https://api.notion.com/v1/pages/PAGE_ID \ -H "Authorization: Bearer $NOTION_TOKEN" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ --data '{ "properties": { "Name": { "title": [ { "text": { "content": "Nouveau titre" } } ] }, "Status": { "status": { "name": "In progress" } }, "Priority": { "select": { "name": "High" } }, "Due date": { "date": { "start": "2026-02-10" } }, "Description": { "rich_text": [ { "text": { "content": "Description mise à jour" } } ] } } }' ``` - **Get database info:** `notion-cli db retrieve <DB_ID>` ## Property Types Common property formats for database items: - **Title:** `{"title": [{"text": {"content": "..."}}]}` - **Rich text:** `{"rich_text": [{"text": {"content": "..."}}]}` - **Status:** `{"status": {"name": "Option"}}` - **Select:** `{"select": {"name": "Option"}}` - **Multi-select:** `{"multi_select": [{"name": "A"}, {"name": "B"}]}` - **Date:** `{"date": {"start": "2024-01-15", "end": "2024-01-16"}}` - **Checkbox:** `{"checkbox": true}` - **Number:** `{"number": 42}` - **URL:** `{"url": "https://..."}` - **Email:** `{"email": "[email protected]"}` ## Examples - **Search for pages:** `notion-cli search --query "AIStories"` - **Query database with filter:** ```bash notion-cli db query 2faf172c094981d3bbcbe0f115457cda \ -a '{ "property": "Status", "status": { "equals": "Backlog" } }' ``` - **Retrieve page content:** `notion-cli page retrieve 2fdf172c-0949-80dd-b83b-c1df0410d91b -r` - **Update page status:** ```bash curl -X PATCH https://api.notion.com/v1/pages/2fdf172c-0949-80dd-b83b-c1df0410d91b \ -H "Authorization: Bearer $NOTION_TOKEN" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2025-09-03" \ --data '{ "properties": { "Status": { "status": { "name": "In progress" } } } }' ``` ## Key Features - *Interactive mode:* For complex queries, run `notion-cli db query <DB_ID>` without arguments to enter interactive mode - *Multiple output formats:* table (default), csv, json, yaml - *Raw JSON:* Use `--raw` flag for complete API responses - *Filter syntax:* Use `-a` flag for complex filters with AND/OR conditions ## Notes - Page/database IDs are UUIDs (with or without dashes) - The CLI handles authentication automatically via *NOTION_TOKEN* - Rate limits are managed by the CLI - Use `notion-cli help` for complete command reference ## References - GitHub Notion-CLI: https://github.com/litencatt/notion-cli - Notion API Documentation: https://developers.notion.com