solid-notion

For Chinese documentation, see README_CN.md.

solid-notion is a CLI that lets humans and AI assistants work with Notion pages in a safer, more practical way.

Instead of treating Notion as a raw JSON API, this tool focuses on three principles:

• Revertable
• Observable
• Auditable

What It Is

solid-notion is a TypeScript CLI for reading, editing, and writing Notion pages with local history.

It supports two core workflows:

• Markdown workflow (pull -> edit -> write -> history -> restore)
• Patch workflow (edit (JSON patch) -> submit -> history -> restore)

The goal is simple: make AI-assisted Notion operations safer and easier to understand.

Why Not Just Call Notion API Directly?

Direct Notion API usage works, but it has real limitations for AI workflows:

• Raw JSON is noisy and token-heavy, especially for large pages
• It is harder to inspect what changed and why
• Rollback is often custom, incomplete, or missing

solid-notion improves this by design.

1) Revertable

Changes are designed to be undone.

• write produces local changesets
• submit produces local version records
• restore can move back to a historical hash by reversing later submit operations
• Restoring to a version also removes local version files after that target hash

This is similar to Git-style safety for content operations.

2) Observable

You can see state clearly, locally, and quickly.

• ls shows pulled pages in local storage
• history shows timeline hashes (changeset, submit, new)
• show page --format markdown gives high-signal content for review

For LLMs, markdown output has much better signal-to-noise ratio than Notion JSON.

3) Auditable

Actions leave local evidence.

• Edit logs
• Version records
• Changesets

This makes it easier to debug, review, and explain what happened after automation runs.

Why It Is Better for LLM-Based Automation

• Lower token cost: markdown is compact compared to Notion block JSON
• Better comprehension: less structural noise, more actual content
• Safer execution: rollback-oriented workflow by default
• Better postmortems: local audit trail for every significant operation

In short: less noise, more control, better safety.

How It Works (High-Level)

1. Pull page content to local files (pull page)
2. Read/edit in markdown or patch form
3. Apply changes (write or submit)
4. Inspect history (history)
5. Restore by hash when needed (restore)

When you run pull page without --outdir, output goes to:

$SOLID_NOTION_HOME/<normalized_page_id>

If a page is already pulled, pulling again fetches the latest content from Notion and overwrites local files.

Key Commands

solid-notion ls [--json]
solid-notion pages
solid-notion search <query>
solid-notion show page <page_id_or_name> [--format markdown|json]
solid-notion pull page <page_id_or_name> [--format json|markdown] [--outdir <dir>]
solid-notion edit <notion_id_or_markdown_path>
solid-notion submit <page_id> -m "message"
solid-notion write <page_id>
solid-notion history <page_id>
solid-notion restore <page_id_or_hash> [changeset_or_commit_id]

Install

For normal usage (after publish to npm):

npm install -g solid-notion
solid-notion --version

Build From Source

pnpm install
pnpm build

Dev validation:

pnpm lint
pnpm typecheck
pnpm test:utils

Who This Is For

• Teams building AI assistants that operate on Notion
• Engineers who need safe, traceable content automation
• Anyone who wants Git-like confidence for Notion edits