| name | notion-cli |
| description | Manage Notion via CLI - pages, databases, blocks, users, search, comments. Use when user mentions 'notion', 'notion page', 'notion database', 'query database', 'notion blocks', 'notion search', 'notion comments', 'workspace users', or wants to interact with the Notion API. |
| category | devtools |
notion-cli
When To Use This Skill
Use notion-cli when you need to:
- Create, retrieve, update, or archive Notion pages
- Create, query, or update Notion databases
- Read, update, delete, or append content blocks
- List workspace users or get bot identity
- Search across the entire Notion workspace
- Add or read comments on pages
Setup
If notion-cli is not found:
bun --version || curl -fsSL https://bun.sh/install | bash
npx api2cli bundle notion
npx api2cli link notion
Always use --json for programmatic calls.
Working Rules
- Always use
--json for agent-driven calls so downstream steps can parse the result.
- Start with
--help if the exact action or flags are unclear instead of guessing.
- Prefer read commands first when you need to inspect current state before mutating data.
- Properties and content use JSON strings - use
--help on specific actions for format details.
Authentication
notion-cli auth set "your-token"
notion-cli auth test
Auth commands: auth set <token>, auth show, auth remove, auth test
Token stored in ~/.config/tokens/notion-cli.txt.
Resources
pages
| Command | Description |
|---|
notion-cli pages get <page-id> --json | Retrieve a page by ID |
notion-cli pages create --parent-id <id> --parent-type database_id --title "My Page" --json | Create a page in a database |
notion-cli pages create --parent-id <id> --parent-type page_id --title "Sub Page" --json | Create a child page |
notion-cli pages create --parent-id <id> --properties '{"Name":{"title":[{"text":{"content":"Hello"}}]}}' --json | Create with custom properties |
notion-cli pages update <page-id> --properties '<json>' --json | Update page properties |
notion-cli pages update <page-id> --icon-emoji "🚀" --json | Update page icon |
notion-cli pages archive <page-id> --json | Archive (soft-delete) a page |
notion-cli pages unarchive <page-id> --json | Restore an archived page |
notion-cli pages get-property <page-id> <property-id> --json | Get a specific property value |
databases
| Command | Description |
|---|
notion-cli databases get <database-id> --json | Retrieve a database schema |
notion-cli databases create --parent-id <page-id> --title "Tasks" --json | Create a database |
notion-cli databases create --parent-id <page-id> --title "CRM" --properties '{"Email":{"email":{}}}' --json | Create with custom schema |
notion-cli databases update <database-id> --title "New Title" --json | Update database title |
notion-cli databases update <database-id> --properties '<json>' --json | Update database schema |
notion-cli databases query <database-id> --json | Query all rows |
notion-cli databases query <database-id> --page-size 10 --json | Query with pagination |
notion-cli databases query <database-id> --filter '{"property":"Status","select":{"equals":"Done"}}' --json | Query with filter |
notion-cli databases query <database-id> --sorts '[{"property":"Created","direction":"descending"}]' --json | Query with sort |
blocks
| Command | Description |
|---|
notion-cli blocks get <block-id> --json | Retrieve a block |
notion-cli blocks update <block-id> --content '{"paragraph":{"rich_text":[{"text":{"content":"Updated"}}]}}' --json | Update block content |
notion-cli blocks delete <block-id> --json | Delete (archive) a block |
notion-cli blocks children <block-id> --json | List child blocks |
notion-cli blocks children <block-id> --page-size 10 --json | List children with pagination |
notion-cli blocks append <block-id> --children '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"text":{"content":"Hello"}}]}}]' --json | Append paragraph block |
notion-cli blocks append <block-id> --children '[{"object":"block","type":"heading_2","heading_2":{"rich_text":[{"text":{"content":"Section"}}]}}]' --json | Append heading block |
users
| Command | Description |
|---|
notion-cli users list --json | List all workspace users |
notion-cli users list --page-size 10 --json | List users with pagination |
notion-cli users get <user-id> --json | Get a user by ID |
notion-cli users me --json | Get the authenticated bot user |
search
| Command | Description |
|---|
notion-cli search query --json | Search all accessible content |
notion-cli search query --text "meeting notes" --json | Search by text |
notion-cli search query --text "tasks" --filter-type database --json | Search only databases |
notion-cli search query --text "project" --filter-type page --json | Search only pages |
notion-cli search query --text "docs" --sort-direction ascending --json | Search with sort |
notion-cli search query --page-size 5 --json | Search with limit |
comments
| Command | Description |
|---|
notion-cli comments list --block-id <page-id> --json | List comments on a page |
notion-cli comments list --block-id <page-id> --page-size 10 --json | List comments with pagination |
notion-cli comments create --page-id <page-id> --text "Great work!" --json | Add comment to a page |
notion-cli comments create --discussion-id <id> --text "Reply" --json | Reply to a discussion thread |
Output Format
--json returns a standardized envelope:
{ "ok": true, "data": { ... }, "meta": { "total": 42 } }
On error: { "ok": false, "error": { "message": "...", "status": 401 } }
Quick Reference
notion-cli --help
notion-cli <resource> --help
notion-cli <resource> <action> --help
Global Flags
All commands support: --json, --format <text|json|csv|yaml>, --verbose, --no-color, --no-header
Exit codes: 0 = success, 1 = API error, 2 = usage error