Notion CLI – Command Line Interface based access to Notion for your agent

Access and manage your Notion workspace via a CLI to search, create, update, and delete pages, databases, blocks, users, and comments with multiple output fo...

Security Scan

The SKILL.md describes a Notion CLI that legitimately needs a Notion API key and to be built from a third‑party GitHub repo, but the registry metadata omits the required credential and the instructions tell you to clone/run third‑party code — this mismatch and the build-from-source guidance warrant caution.

Purpose & Capability

The skill name and SKILL.md are consistent with a Notion CLI (operations and examples match the Notion API). However the registry metadata provides no description and does not declare the Notion API key (primary credential) even though the instructions explicitly require NOTION_API_KEY.

Instruction Scope

Runtime instructions are focused on Notion CLI usage and how to call the Notion API. They do not ask the agent to read unrelated system files, but they do recommend adding an API key into agent or shell env files (e.g., ~/.claude/.env or ~/.bashrc), which is expected for functionality but is a scope/handling decision the user should consider carefully.

Install Mechanism

There is no automated install spec in the registry; SKILL.md tells the user/agent to git clone a third‑party GitHub repository and run npm install/build/link. Cloning and building arbitrary third‑party code is potentially risky if done automatically — GitHub is a common host, but the skill does not declare that it will or will not perform this action itself.

Credentials

The instructions require NOTION_API_KEY (and optionally NOTION_DEBUG) but the skill metadata lists no required environment variables or primary credential. This mismatch is an incoherence: the skill needs a secret to function but does not declare it in its requirements, so a user/agent may not be aware of the credential scope ahead of time.

Persistence & Privilege

The skill is not marked always:true, declares no config paths to modify, and has no code in the package — it does not request elevated persistence or platform-wide privileges in the registry metadata.

What to consider before installing

This skill appears to be a wrapper for a third‑party Notion CLI and reasonably requires your Notion integration key, but the registry metadata omits that requirement and the SKILL.md instructs cloning and building a GitHub repo. Before installing or running these commands: 1) Verify the GitHub repository and review its code (npm install/build runs arbitrary JavaScript). 2) Prefer using the --api-key option for one-off runs rather than permanently storing the key in shell rc files, and create a scoped Notion integration with minimal permissions. 3) If you expect the skill to be self‑contained, ask the publisher why the registry metadata doesn't declare NOTION_API_KEY. 4) If you cannot or will not review the repo, consider using an official Notion SDK or a skill that explicitly declares required credentials and an install mechanism.

notion-cli Interact with your Notion workspace via the notion-cli.

A production-grade CLI for the Notion API that supports searching, creating and managing pages, databases, blocks, users, and comments with multiple output formats (JSON, table, CSV).

Install Clone and install the CLI:

git clone https://github.com/FroeMic/notion-cli
cd notion-cli
npm install
npm run build
npm link

Set NOTION_API_KEY environment variable:

1. Create an integration at https://www.notion.so/profile/integrations
2. Copy the Internal Integration Secret (starts with ntn_ or secret_)
3. Share any pages/databases you want to access with the integration

• Recommended: Add to ~/.claude/.env for Claude Code
• Alternative: Add to ~/.bashrc or ~/.zshrc: export NOTION_API_KEY="your-api-key"

Optional: Set NOTION_DEBUG=true for verbose request/response logging.

Repository: https://github.com/FroeMic/notion-cli

Commands Search across your workspace:

notion search [query]                                  # Search pages, databases, and data sources
notion search [query] --filter page                    # Search only pages
notion search [query] --filter database                # Search only databases
notion search [query] --sort ascending                 # Sort by last edited time

Work with pages:

notion pages get <page-id>                             # Get page details
notion pages create --parent <id> --title <text>       # Create a new page
notion pages update <page-id> --properties <json>      # Update page properties
notion pages archive <page-id>                         # Archive a page
notion pages restore <page-id>                         # Restore an archived page
notion pages property <page-id> <property-id>          # Get a specific property value

Work with databases:

notion databases get <database-id>                     # Get database schema
notion databases create --parent <id> --title <text>   # Create a database
notion databases update <database-id> --title <text>   # Update database metadata
notion databases query <data-source-id>                # Query records in a data source
notion databases query <id> --filter <json>            # Query with filters
notion databases query <id> --sort <json>              # Query with sorting

Work with blocks (page content):

notion blocks get <block-id>                           # Get a block
notion blocks children <block-id>                      # List child blocks
notion blocks append <block-id> --content <json>       # Append new blocks
notion blocks update <block-id> --content <json>       # Update a block
notion blocks delete <block-id>                        # Delete a block

Work with users:

notion users list                                      # List workspace members
notion users get <user-id>                             # Get user details
notion users me                                        # Get the authenticated bot user

Work with comments:

notion comments list --block <block-id>                # List comments on a block
notion comments create --page <page-id> --content <text>  # Add a comment to a page

Global options (available on all commands):

--api-key <key>                                        # Override NOTION_API_KEY env var
-f, --format <fmt>                                     # Output format: json (default), table, csv
--limit <n>                                            # Max results to return
--cursor <cursor>                                      # Pagination cursor

Key Concepts

Concept	Purpose	Example
Pages	Individual Notion pages	A meeting note, a project brief
Databases	Structured collections of pages	A task tracker, a CRM table
Data Sources	Individual tables within a database	A specific view/table in a database
Blocks	Content elements within a page	Paragraphs, headings, lists, code blocks
Properties	Typed fields on database pages	Title, status, date, select, relation
Users	Workspace members and integrations	Team members, bot integrations
Comments	Discussion threads on pages/blocks	Feedback, review notes

API Reference

• Base URL: https://api.notion.com/v1
• API Version: 2022-06-28
• Auth: Authorization: Bearer $NOTION_API_KEY
• Rate Limits: Automatic retry with exponential backoff (up to 3 retries)

Common API Operations Search for a page:

curl -X POST https://api.notion.com/v1/search \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"query": "Meeting Notes", "filter": {"value": "page", "property": "object"}}'

Query a database with filters:

curl -X POST https://api.notion.com/v1/databases/<database-id>/query \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"property": "Status", "status": {"equals": "In Progress"}}}'

Create a page in a database:

curl -X POST https://api.notion.com/v1/pages \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"parent": {"database_id": "<database-id>"}, "properties": {"Name": {"title": [{"text": {"content": "New Task"}}]}}}'

Append content to a page:

curl -X PATCH https://api.notion.com/v1/blocks/<block-id>/children \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" \
  -H "Content-Type: application/json" \
  -d '{"children": [{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Hello world"}}]}}]}'

Notes

• The integration must be explicitly shared with each page or database you want to access (via Notion UI: ... menu > Connections > Add your integration).
• Pages can accept IDs as UUIDs or Notion URLs — the CLI will parse both formats.
• All list endpoints support cursor-based pagination via --limit and --cursor.
• Output format can be set to json (default), table, or csv with the -f flag.
• Property types include: title, rich_text, number, select, multi_select, status, date, people, files, checkbox, url, email, phone_number, relation, rollup, formula, and timestamp fields.

Files 1 total

• SKILL.md (this file)