Notion

Notion API for creating and managing pages, databases, blocks, relations, rollups, and multi-workspace profiles via the notioncli CLI tool.

Security Scan

The skill largely matches a Notion CLI integration, but there are inconsistencies in the packaging/metadata and some install/credential handling details that you should verify before installing.

Purpose & Capability

The SKILL.md describes a Notion CLI (create/update/delete pages, query DBs, comments, users) and declares NOTION_API_KEY and an npm install of @jordancoin/notioncli — which is appropriate for this purpose. However, the registry metadata above says 'Required env vars: none' and 'No install spec', which contradicts the SKILL.md. Also SKILL.md expects npm to be available but the skill doesn't declare npm as a required binary.

Instruction Scope

The runtime instructions stay within Notion management (listing DBs, creating/updating pages, comments). They instruct running 'notion init --key $NOTION_API_KEY' which will 'save your API key' and auto-discover databases. The SKILL.md does not say where or how the key is stored (file path, encryption), which is a privacy/security detail worth verifying.

Install Mechanism

Install is via npm global package (@jordancoin/notioncli) referenced in SKILL.md metadata. Installing a global npm package is a moderate risk: it runs third-party code on your system. The registry claims 'no install spec', yet SKILL.md provides an npm install command and an install.sh file exists in the bundle — this packaging inconsistency increases risk because it's unclear which install path the marketplace expects to run.

Credentials

NOTION_API_KEY is the single credential the CLI needs and is proportional to the functionality. But the marketplace metadata omitted that requirement, and SKILL.md's 'init' will persist the key locally without describing storage/permissions. You should ensure the API key has minimal scopes and confirm where the key is saved.

Persistence & Privilege

No 'always: true' and no special persistent privileges are requested. Model invocation settings are default (model can invoke), which is typical for a user-invoked integration.

What to consider before installing

This appears to be a legitimate Notion CLI skill, but verify a few things before installing: 1) Confirm the npm package author (@jordancoin) and review the package source (the GitHub repo) to ensure it's the expected code. 2) Check where 'notion init' stores your NOTION_API_KEY and whether it's encrypted or stored plaintext; prefer storing keys in a secure vault. 3) Limit the API key's scopes to only the databases/workspaces needed. 4) Because the registry metadata contradicts the SKILL.md (env/install omissions) and an install.sh is present, prefer installing in a controlled environment or inspect the install.sh contents first. If you are not comfortable inspecting code, avoid global npm installs from unverified publishers.

notioncli — Notion API Skill

A powerful CLI for the Notion API. Query databases, manage pages, add comments, and automate your workspace from the terminal. Built for AI agents and humans alike.

Setup

npm install -g notioncli
notion init --key $NOTION_API_KEY

The init command saves your API key and auto-discovers all databases shared with your integration. Each database gets an alias (a short slug derived from the database title) so you never need to type raw UUIDs.

Tip: In Notion, you must share each database with your integration first: open the database → ••• menu → Connections → Add your integration.

Auto-Aliases

When you run notion init, every shared database is automatically assigned a slug alias:

Found 3 databases:

  ✅ projects                   → Projects
  ✅ tasks                      → Tasks  
  ✅ reading-list               → Reading List

You can then use projects instead of a1b2c3d4-e5f6-... everywhere. Manage aliases manually with:

notion alias list                  # Show all aliases
notion alias add mydb <db-id>     # Add a custom alias
notion alias rename old new        # Rename an alias
notion alias remove mydb           # Remove an alias

Commands Reference

Database Discovery

notion dbs                         # List all databases shared with your integration
notion alias list                  # Show configured aliases with IDs

Querying Data

notion query tasks                                     # Query all rows
notion query tasks --filter Status=Active              # Filter by property
notion query tasks --sort Date:desc                    # Sort results
notion query tasks --filter Status=Active --limit 10   # Combine options
notion query tasks --output csv                        # CSV output
notion query tasks --output yaml                       # YAML output
notion query tasks --output json                       # JSON output
notion --json query tasks                              # JSON (shorthand)

Output formats:

• table — formatted ASCII table (default)
• csv — header row + comma-separated values
• json — full API response as JSON
• yaml — simple key/value YAML format

Creating Pages

notion add tasks --prop "Name=Buy groceries" --prop "Status=Todo"
notion add projects --prop "Name=New Feature" --prop "Priority=High" --prop "Due=2026-03-01"

Multiple --prop flags for multiple properties. Property names are case-insensitive and matched against the database schema.

Updating Pages

By page ID:

notion update <page-id> --prop "Status=Done"
notion update <page-id> --prop "Priority=Low" --prop "Notes=Updated by CLI"

By alias + filter (zero UUIDs):

notion update tasks --filter "Name=Ship feature" --prop "Status=Done"
notion update workouts --filter "Name=LEGS #5" --prop "Notes=Great session"

Reading Pages & Content

By page ID:

notion get <page-id>               # Page properties
notion blocks <page-id>            # Page content (headings, text, lists, etc.)

By alias + filter:

notion get tasks --filter "Name=Ship feature"
notion blocks tasks --filter "Name=Ship feature"

Deleting (Archiving) Pages

notion delete <page-id>                              # By page ID
notion delete tasks --filter "Name=Old task"         # By alias + filter
notion delete workouts --filter "Date=2026-02-09"    # By alias + filter

Relations & Rollups

notion relations tasks --filter "Name=Ship feature"           # See linked pages with titles
notion relations projects --filter "Name=Launch CLI"          # Explore connections

Relations are automatically resolved to page titles in get output. Rollups are parsed into numbers, dates, or arrays instead of raw JSON.

Blocks CRUD

notion blocks tasks --filter "Name=Ship feature"              # View page content
notion blocks tasks --filter "Name=Ship feature" --ids        # View with block IDs
notion append tasks "New paragraph" --filter "Name=Ship feature"  # Append block
notion block-edit <block-id> "Updated text"                   # Edit a block
notion block-delete <block-id>                                # Delete a block

Use --ids to get block IDs, then target specific blocks with block-edit or block-delete.

Appending Content

notion append <page-id> "Meeting notes: discussed Q2 roadmap"
notion append tasks "Status update: phase 1 complete" --filter "Name=Ship feature"

Appends a paragraph block to the page.

Users

notion users                       # List all workspace users
notion user <user-id>              # Get details for a specific user

Comments

notion comments <page-id>                                      # By page ID
notion comments tasks --filter "Name=Ship feature"             # By alias + filter
notion comment <page-id> "Looks good, shipping this!"          # By page ID
notion comment tasks "AI review complete ✅" --filter "Name=Ship feature"  # By alias + filter

Page Inspector

notion props tasks --filter "Name=Ship feature"    # Quick property dump
notion me                                          # Show bot identity and owner

Database Management

notion db-create <parent-page-id> "New DB" --prop "Name:title" --prop "Status:select"
notion db-update tasks --add-prop "Rating:number"      # Add a column
notion db-update tasks --remove-prop "Old Column"      # Remove a column
notion db-update tasks --title "Renamed DB"            # Rename database
notion templates tasks                                 # List page templates

Moving Pages

notion move tasks --filter "Name=Done task" --to archive     # Move by alias
notion move tasks --filter "Name=Done task" --to <page-id>   # Move to page

File Uploads

notion upload tasks --filter "Name=Ship feature" ./report.pdf
notion upload <page-id> ./screenshot.png

Supports images, PDFs, text files, documents. MIME types auto-detected from extension.

Search

notion search "quarterly report"   # Search across all pages and databases

JSON Output

Add --json before any command to get the raw Notion API response:

notion --json query tasks
notion --json get <page-id>
notion --json users
notion --json comments <page-id>

Common Patterns for AI Agents

1. Discover available databases

notion dbs
notion alias list

2. Query and filter data

notion query tasks --filter Status=Active --sort Date:desc
notion --json query tasks --filter Status=Active    # Parse JSON programmatically
notion query tasks --output csv                     # CSV for spreadsheet tools

3. Create a new entry

notion add tasks --prop "Name=Review PR #42" --prop "Status=Todo" --prop "Priority=High"

4. Update an existing entry (zero UUIDs)

# By alias + filter — no page ID needed
notion update tasks --filter "Name=Review PR #42" --prop "Status=Done"

# Or by page ID if you already have it
notion update <page-id> --prop "Status=Done"

5. Read page content (zero UUIDs)

# By alias + filter
notion get tasks --filter "Name=Review PR #42"
notion blocks tasks --filter "Name=Review PR #42"

# Or by page ID
notion get <page-id>
notion blocks <page-id>

6. Append notes to a page

notion append tasks "Status update: completed phase 1" --filter "Name=Review PR #42"
notion append <page-id> "Status update: completed phase 1"

7. Collaborate with comments

notion comments tasks --filter "Name=Review PR #42"              # Check existing
notion comment tasks "AI review complete ✅" --filter "Name=Review PR #42"  # Add comment

# Or by page ID
notion comments <page-id>
notion comment <page-id> "AI review complete ✅"

8. Delete by alias + filter

notion delete tasks --filter "Name=Old task"
notion delete workouts --filter "Date=2026-02-09"

9. Manage database schema

notion db-update tasks --add-prop "Priority:select"    # Add column
notion db-update tasks --remove-prop "Old Field"       # Remove column
notion db-create <parent-page-id> "New DB" --prop "Name:title" --prop "Status:select"

10. Move pages and upload files

notion move tasks --filter "Name=Done" --to archive
notion upload tasks --filter "Name=Ship feature" ./report.pdf

11. Inspect and debug

notion me                                       # Check integration identity
notion props tasks --filter "Name=Ship feature" # Quick property dump
notion templates tasks                          # List available templates

Property Type Reference

When using --prop key=value, the CLI auto-detects the property type from the database schema:

Type	Example Value	Notes
title	Name=Hello World	Main title property
rich_text	Notes=Some text	Plain text content
number	Amount=42.5	Numeric values
select	Status=Active	Single select option
multi_select	Tags=bug,urgent	Comma-separated options
date	Due=2026-03-01	ISO 8601 date string
checkbox	Done=true	true, 1, or yes
url	Link=https://example.com	Full URL
email	Contact=[e-mail]	Email address
phone_number	Phone=[phone]	Phone number string
status	Status=In Progress	Status property

Multi-Workspace Profiles

Manage multiple Notion accounts from one CLI:

notion workspace add work --key ntn_work_key       # Add workspace
notion workspace add personal --key ntn_personal    # Add another
notion workspace list                               # Show all
notion workspace use work                           # Switch active
notion workspace remove old                         # Remove one

# Per-command override
notion query tasks --workspace personal
notion -w work add projects --prop "Name=Q2 Plan"

# Init with workspace
notion init --workspace work --key ntn_work_key

Aliases are scoped per workspace. Old single-key configs auto-migrate to a "default" workspace.

Notion API 2025 — Dual IDs

The Notion API (2025-09-03) uses dual IDs for databases: a database_id and a data_source_id. notioncli handles this automatically — when you run notion init or notion alias add, both IDs are discovered and stored. You never need to think about it.

Troubleshooting

• "No Notion API key found" — Run notion init --key ntn_... or export NOTION_API_KEY=ntn_...
• "Unknown database alias" — Run notion alias list to see available aliases, or notion init to rediscover
• "Not found" errors — Make sure the database/page is shared with your integration in Notion
• Filter/sort property not found — Property names are case-insensitive; run notion --json query <alias> --limit 1 to see available properties