Notion CLI

A command-line interface for interacting with the Notion API.

Features

• Pages: Create, read, update, and archive pages
• Blocks: Add, edit, and delete page content
• Databases: Query, create items, and update database entries
• Database Shortcuts: Quick task management (add-task, complete-task, list-tasks)
• Search: Search across your entire workspace
• Comments: View and add comments to pages
• Users: List workspace users and bot info
• Templates: Create pages from built-in templates
• Export/Import: Export pages to Markdown/JSON, import from Markdown
• Backup: Full workspace backup
• Multiple Output Formats: JSON, Table, CSV, YAML, Pretty
• Config Profiles: Multiple workspace support

Installation

Prerequisites

• .NET 6.0 SDK or later

Install as Global Tool

cd src
dotnet pack -c Release
dotnet tool install --global --add-source ./nupkg NotionCli

Verify Installation

notion-cli --version

Uninstall

dotnet tool uninstall --global NotionCli

Quick Start

1. Create a Notion Integration

1. Go to Notion Integrations
2. Click "New integration"
3. Name your integration and select your workspace
4. Copy the "Internal Integration Token"

2. Share Pages with Integration

1. Open a page in Notion
2. Click "..." menu → "Connections" → Select your integration

3. Configure CLI

notion-cli --set-auth secret_your_token_here
notion-cli --check-auth

Usage

Authentication

notion-cli --set-auth <token>              # Save token
notion-cli --set-auth <token> --profile work   # Save to named profile
notion-cli --check-auth                    # Verify token works
notion-cli --clear-auth                    # Remove saved token
notion-cli --list-profiles                 # List all saved profiles

Pages

notion-cli --get-page <page-id>
notion-cli --create-page <parent-id> --title "My Page" --icon "📝"
notion-cli --create-page <parent-id> --title "My Page" --template meeting-notes
notion-cli --update-page <page-id> --title "New Title"
notion-cli --archive-page <page-id>

Blocks (Page Content)

notion-cli --get-blocks <page-id>
notion-cli --get-blocks <page-id> --all                    # Get all blocks (auto-paginate)
notion-cli --get-block <block-id>
notion-cli --append-block <page-id> --type paragraph --content "Hello World"
notion-cli --append-block <page-id> --type heading_1 --content "Title"
notion-cli --append-blocks <page-id> --file blocks.json    # Bulk append from file
notion-cli --update-block <block-id> --content "Updated text"
notion-cli --delete-block <block-id>

Available block types:

• paragraph, heading_1, heading_2, heading_3
• bulleted_list_item, numbered_list_item
• to_do, quote, callout, toggle, divider, code

Databases

notion-cli --get-database <db-id>
notion-cli --query-database <db-id>
notion-cli --query-database <db-id> --all                  # Get all items (auto-paginate)
notion-cli --query-database <db-id> --filter '{"property":"Status","select":{"equals":"Done"}}'
notion-cli --create-db-item <db-id> --props '{"Name":{"title":[{"text":{"content":"Task"}}]}}'
notion-cli --update-db-item <item-id> --props '{"Status":{"select":{"name":"Done"}}}'

Database Shortcuts (Task Management)

notion-cli --add-task <db-id> --name "Review PR" --status "In Progress" --due "2024-12-31"
notion-cli --complete-task <task-id>
notion-cli --list-tasks <db-id>
notion-cli --list-tasks <db-id> --status "In Progress"

Search

notion-cli --search "meeting notes"
notion-cli --search "project" --filter page
notion-cli --search "tasks" --filter database
notion-cli --search "notes" --all                          # Get all results (auto-paginate)

Comments

notion-cli --get-comments <page-id>
notion-cli --add-comment <page-id> --content "This is a comment"
notion-cli --add-comment <page-id> --content "Reply" --discussion <discussion-id>

Users

notion-cli --get-users                                     # List all users
notion-cli --get-user <user-id>                            # Get specific user
notion-cli --get-me                                        # Get bot user info

Templates

notion-cli --list-templates                                # List available templates
notion-cli --create-page <parent-id> --template meeting-notes --title "Weekly Sync"

Available templates:

• meeting-notes - Meeting notes with attendees, agenda, and action items
• task-list - Simple task list with checkboxes
• project-brief - Project overview with goals, timeline, and resources
• weekly-review - Weekly review with accomplishments and next week plans
• bug-report - Bug report template with steps to reproduce

Export & Import

# Export page
notion-cli --export-page <page-id>                                    # Output to console
notion-cli --export-page <page-id> --export-format markdown --output page.md
notion-cli --export-page <page-id> --export-format json --output page.json

# Import markdown
notion-cli --import-markdown <page-id> --file content.md

# Backup entire workspace
notion-cli --backup --output workspace-backup.json

Output Formats

notion-cli --search "notes" --format json      # Default JSON
notion-cli --search "notes" --format table     # Table view
notion-cli --search "notes" --format csv       # CSV format
notion-cli --search "notes" --format yaml      # YAML format
notion-cli --search "notes" --format pretty    # Pretty-printed JSON

Config Profiles (Multiple Workspaces)

# Save different tokens for different workspaces
notion-cli --set-auth secret_personal_token
notion-cli --set-auth secret_work_token --profile work

# Use specific profile
notion-cli --search "notes" --profile work
notion-cli --get-page <id> --profile work

# List all profiles
notion-cli --list-profiles

Response Format

All responses are JSON:

Success:

{"ok":true,"data":{...}}

Error:

{"ok":false,"error":"Error message","code":"ERROR_CODE"}

Environment Variables

Instead of --set-auth, you can use environment variables:

export NOTION_API_KEY=secret_your_token_here
# or
export NOTION_TOKEN=secret_your_token_here

Finding Page/Database IDs

The ID is the 32-character string in the URL:

https://notion.so/My-Page-abc123def456...
                        ^^^^^^^^^^^^^^^^
                        This is the ID

Error Codes

Code	Description
AUTH_ERROR	Invalid or missing authentication
NOT_FOUND	Resource not found or not shared with integration
RATE_LIMIT	Too many requests
BAD_REQUEST	Invalid request parameters
MISSING_PARAM	Required parameter not provided
INVALID_PARAM	Parameter value is invalid
HTTP_ERROR	Network error

Documentation

• Complete Reference - Detailed command documentation
• Notion API Docs - Official API documentation

License

MIT