notion-cli_skill

Overview

This skill provides a command-line interface for creating, reading, updating, and managing Notion pages, databases, and blocks. It exposes search, page and database retrieval, query, and update operations with multiple output formats and an interactive query mode. It relies on a Notion integration token and automates authentication and rate-limit handling.

How this skill works

The CLI reads your NOTION_TOKEN (or an api_key file) and interacts with the Notion REST API to perform CRUD operations on pages, databases, and blocks. Commands include search, page retrieve (with optional recursive block fetch), db query with filter JSON, and create/update endpoints using Notion property payloads. Output can be table, csv, json, yaml, or raw API JSON.

When to use it

• Automate repeated updates to Notion pages or database items from scripts and CI jobs.
• Bulk-query or export database rows in CSV/JSON/YAML for reporting and backups.
• Quickly search and inspect page content and nested blocks from the terminal.
• Create new pages in a database or update properties without opening the web UI.
• Integrate Notion data manipulation into shell pipelines and cron jobs.

Best practices

• Store your integration token securely (e.g., ~/.config/notion/api_key) and export NOTION_TOKEN in your shell session.
• Share target pages and databases with your integration in Notion so the CLI has permission.
• Use the --raw flag when you need full API responses for debugging or precise scripting.
• Test updates on a staging database or page before running bulk patches to avoid accidental data loss.
• Use interactive db query mode for building complex filter JSON before automating it in scripts.

Example use cases

• Search for project pages: notion-cli search --query "Roadmap" and then retrieve content with page retrieve <PAGE_ID> -r.
• Export active tasks to CSV for processing: notion-cli db query <DB_ID> -a '{"property":"Status","status":{"equals":"Active"}}' --output csv.
• Create a new database entry via curl or the CLI with the appropriate title, status, and date properties.
• Update a page status and priority programmatically using a PATCH request or notion-cli page update workflow.
• Retrieve database schema and metadata: notion-cli db retrieve <DB_ID> to inspect property types for automation.