notion-cli

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                    # List all resources and global flags
notion-cli <resource> --help         # List all actions for a resource
notion-cli <resource> <action> --help # Show flags for a specific action

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