GitHub - vincentdchan/solid-notion: The open-source CLI that turns Notion into a Git-like workflow — pull, edit, submit, and restore pages as Markdown

3 min read Original article ↗

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.

Use this tool with OpenClaw skill: https://clawhub.ai/vincentdchan/solid-notion

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 and editing Notion pages with local history.

It supports two core workflows:

  • Read workflow (pull -> inspect)
  • Patch workflow (edit (JSON patch) -> submit -> history -> restore)

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

A Gentle Heads Up: This is an experimental project that I built to meet my own needs. While it's designed to help you safely experiment with changes, I can't guarantee that every restore will be perfect. Please try it out, but use it at your own risk — especially with important pages.

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.

  • submit produces local version records
  • restore moves back to a historical hash by reversing later submit operations
  • Restoring to a version removes local version files after that target hash and writes a new changeset

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 (edit + 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 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

Getting a Notion Token

Before you can use this CLI, you need to create a Notion integration and get an API token:

  1. Go to https://www.notion.so/profile/integrations/internal
  2. Click "New integration" and give it a name
  3. Copy the "Internal Integration Token"
  4. Use it with solid-notion init --token-stdin

Build From Source

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