agent-notion

Notion CLI for humans and LLMs

TypeScript v0.2.1 MIT

A modern CLI for Notion that prioritizes structured JSON output and LLM-optimized interaction. It provides full CRUD access to pages, databases, blocks, and comments, plus AI chat integration — all as a zero-dependency single binary.

Features

Structured JSON output — all output to stdout, errors to stderr

LLM-optimized docs via agent-notion usage for agent consumption

Full CRUD — search, read, create, update, and archive pages and databases

Markdown conversion — page content rendered as markdown, append from markdown

Notion AI chat — send messages, list models and threads, stream responses

OAuth and integration token auth with multi-workspace management

Inline and page-level comments with text anchoring

Page export with recursive mode and workspace-wide export

Version history snapshots and activity log

macOS Keychain integration for secure credential storage

Zero runtime dependencies — single compiled binary

Install

Homebrew

$ brew install shhac/tap/agent-notion

AI Agent Skill

$ npx skills add shhac/agent-notion

GitHub Release (macOS)

$ curl -L https://github.com/shhac/agent-notion/releases/latest/download/agent-notion-darwin-arm64.tar.gz | tar xz

Build from Source

$ git clone https://github.com/shhac/agent-notion.git && cd agent-notion && bun install && bun run build

Getting Started

agent-notion requires authentication before any commands will work. The simplest option is an integration token; for access to advanced features like AI chat and export, import your desktop session.

1. Option A: Use an integration token

$ agent-notion auth login --token ntn_...

Create an internal integration at notion.so/profile/integrations and copy its token. Share pages/databases with the integration to grant access.

2. Option B: Import your desktop session

$ agent-notion auth import-desktop

macOS only. Reads the session token from the Notion desktop app. Grants access to v3 API features like AI chat, export, backlinks, and activity log.

3. Verify authentication

$ agent-notion auth status

Usage

Search pages by title

$ agent-notion search "Meeting Notes"

Query a database with filters

$ agent-notion database query DB_ID --filter status=Done

Read a page as markdown

$ agent-notion page get PAGE_ID --content

Append markdown to a page

$ agent-notion block append PAGE_ID --markdown "## New Section"

Chat with Notion AI

$ agent-notion ai chat send "Summarize my recent notes"