@sakasegawa/ncli

ncli

Disclaimer: ncli is an unofficial, community-built tool. It is not developed, endorsed, or supported by Notion Labs, Inc.

日本語

CLI for Notion — MCP + REST API support. Read and write Notion from the terminal.

Designed for both humans and coding agents (Claude Code, Codex, etc.). All output is structured JSON with recovery hints on errors.

Features

• Full Notion workspace access: search, pages, databases, views, comments, users, teams, meeting notes
• REST API direct access: ncli rest for arbitrary Notion API calls
• File upload: ncli file upload for attaching files to pages
• Dual auth: OAuth (MCP commands) + integration token (NOTION_API_KEY env var or ncli rest login)
• OAuth 2.0 + PKCE authentication (browser-based, zero-config)
• Agent-first design: --json output, structured error hints (What + Why + Hint)
• Escape hatch: ncli api <tool> [json] for direct MCP tool access
• Single bundled ESM binary, Node.js >= 18

Install

npm install -g @sakasegawa/ncli

Quick Start

# Authenticate (opens browser, one-time)
ncli login

# Search and fetch
ncli search "project plan"
ncli fetch <id>

# Create and update pages
ncli page create --title "New Page" --parent <page-id>
ncli page update <id> --prop "Status=Done"

# Database workflow
ncli db create --title "Tasks" --parent <page-id> \
  --prop "Name:title" --prop "Status:select=Open,Done"
ncli page create --parent collection://<ds-id> \
  --title "Task 1" --prop "Status=Open"

REST API

# REST API setup (integration token)
ncli rest login

# Call REST API directly
ncli rest GET /users/me
ncli rest GET /pages/<page-id>

# Upload a file
ncli file upload ./image.png

Commands

Command	Description
ncli login	Log in to Notion via OAuth
ncli logout	Log out from Notion
ncli whoami	Show current Notion user info
ncli search <query>	Search pages, databases, and users across workspace
ncli fetch <url-or-id>	Retrieve a page, database, or data source by URL or ID
ncli page create	Create a page (with --title, --parent, --prop, --body)
ncli page update <id>	Update page properties or content
ncli page move <id...> --to <parent>	Move pages to a new parent
ncli page duplicate <id>	Duplicate a page
ncli db create	Create a database (with --title, --parent, --prop, or --schema)
ncli db update <id>	Update database schema or metadata
ncli db query <view-url>	Query a database view
ncli view create	Create a database view (via --data)
ncli view update	Update a database view (via --data)
ncli comment create <id>	Add a comment to a page
ncli comment list <id>	List comments on a page
ncli user list	List and search workspace users
ncli team list	List and search workspace teams
ncli meeting-notes query	Query meeting notes with filters
ncli rest login	Save REST API integration token
ncli rest logout	Remove saved REST API token
ncli rest <METHOD> <path> [json]	Call any Notion REST API endpoint directly
ncli file upload <file-path>	Upload a file (returns file_upload_id for attaching to pages)
ncli api <tool> [json]	Call any MCP tool directly (escape hatch)

Run ncli <command> --help for detailed usage, examples, and tips.

Common Workflows

Search, fetch, and update

ncli search "Project Plan"               # Find pages/databases
ncli fetch <id>                           # Get content and metadata
ncli page update <id> --prop "Status=Done"  # Update properties

Create a database and add entries

# Create a database under a page
ncli db create --title "Tasks" --parent <page-id> \
  --prop "Name:title" --prop "Status:select=Open,Done"

# Response includes data_source_id (collection://...)
# Create entries using that ID
ncli page create --parent collection://<ds-id> \
  --title "Task 1" --prop "Status=Open"

# Create a view and query
ncli view create --data '{"database_id":"<db-id>","data_source_id":"collection://<ds-id>","type":"table","name":"All"}'
ncli db query "https://www.notion.so/<db-id>?v=<view-id>"

Pipe content from stdin

echo "# Meeting Notes" | ncli page create --title "Notes" --parent <id> --body -

Global Flags

Flag	Description
--json	Output as JSON (structured, parseable)
--raw	Output raw MCP response (full server payload)
--verbose	Verbose output
--no-color	Disable colors

Agent Usage

This CLI is optimized for coding agents. Key patterns:

• Use --json for structured, parseable output
• Errors include recovery hints: What happened, Why, and what to do next
• Workflow: search → fetch (get IDs/schema) → create/update/query
• For databases: always ncli fetch <db-id> first to get data_source_id

Error example:

Error: notion-create-pages failed
  Why: Could not find page with ID: abc123...
  Hint: If adding to a database, use --data with "parent":{"data_source_id":"<ds-id>",...}.
        Run "ncli fetch <db-id>" to get the data_source_id

Escape Hatch

For advanced use or unsupported operations, call any MCP tool directly:

ncli api notion-search '{"query":"test","page_size":3}'
echo '{"query":"test"}' | ncli api notion-search

Requirements

• Node.js >= 18
• A Notion account (OAuth authentication via browser)
• Notion integration token (for REST API commands — get at https://www.notion.so/profile/integrations)

Legal

• Terms of Use
• Privacy Policy

License

MIT