Do I need to share databases with the integration?

Yes. Notion requires sharing each database with your Notion integration before it can be discovered and managed by notioncli.

How does aliasing work and how can I switch references?

When you run notion init, Notion auto-discovers shared databases and assigns slug aliases. You can list, add, rename, or remove aliases with the alias commands to reference databases by name instead of IDs.

What output formats does notioncli support for data?

Output formats include table (default), csv, json, and yaml, accessible via --output or shorthand options like notion --json query or notion query --output json.

Notion

Scanned

@JordanCoin

npx machina-cli add skill @JordanCoin/notioncli --openclaw

Files (1)

SKILL.md

11.2 KB

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=user@example.com`	Email address
`phone_number`	`Phone=+1234567890`	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

Source

git clone https://clawhub.ai/JordanCoin/notioncliView on GitHub

Overview

notioncli is a powerful CLI for the Notion API that lets you query databases, manage pages and blocks, and automate work across multiple Notion workspaces from the terminal. It auto-discovers databases shared with your integration and assigns slug aliases so you can reference them by name instead of UUIDs. This makes AI agents and humans perform Notion operations without the GUI.

How This Skill Works

Install globally with npm and authenticate using notion init --key $NOTION_API_KEY. On first run, it auto-discovers all databases shared with your integration and creates slug aliases for easy reference. From there, use commands like notion add, notion update, notion get, notion blocks, and notion query to manage data; outputs support table, csv, json, and yaml for downstream tooling.

When to Use It

Manage Notion data across multiple workspaces by referencing databases via auto-generated slug aliases.
Query databases and export results (CSV/JSON) for AI agents or external tooling with no GUI.
Bulk-update pages or entries using alias + filter to reflect status changes or due dates.
Read a page's content and blocks to generate summaries or feed into other processes.
Programmatically create new pages or databases with structured properties using --prop flags.

Quick Start

Step 1: Install and authenticate - npm install -g notioncli; notion init --key $NOTION_API_KEY
Step 2: Let notioncli auto-discover databases and create aliases - run notion init again and/or inspect with notion alias list
Step 3: Try a common task - notion query tasks --filter "Status=Active" --output json or create a page with notion add projects --prop "Name=New Feature" --prop "Priority=High" --prop "Due=2026-03-01"

Best Practices

Ensure every database is shared with your Notion integration before running init so auto-discovery works.
Use aliases (not raw IDs) to reference databases; manage them with alias list/add/rename/remove.
Leverage --output options (csv/json/yaml) for machine-readable results and automation pipelines.
Test bulk operations on a small sandbox database before applying them to production data.
When using relations and rollups, validate schema compatibility to avoid mismatched properties.

Example Use Cases

Auto-discover and alias all databases in a workspace, then query tasks with a filter and export as JSON for an agent.
Create a new feature page under Projects with Name, Priority, and Due properties in one command.
Update all Active tasks to Done using alias + filter and a single update operation.
Retrieve a page's content and blocks to generate a succinct briefing document.
Switch between multiple workspace contexts by using database aliases and dedicated profiles for each workspace.

Frequently Asked Questions

Add this skill to your agents