Solid Notion

solid-notion CLI Guide

solid-notion is a CLI for reading, editing, and writing Notion pages as Markdown with local reversible changesets.

0. Installation

For normal usage (published package):

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

For local development from source:

pnpm install
pnpm build

1. Authentication Setup

Before using any command that talks to Notion, a token must be configured.

Getting a Notion Token

Create a Notion integration to get an API token:

1. Visit https://www.notion.so/profile/integrations/internal
2. Click "New integration" and give it a name
3. Copy the "Internal Integration Token"
4. Share your pages with this integration (via page "Share" settings)

Check current auth status

solid-notion auth status --json

Returns:

{
  "ok": true,
  "profile": "default",
  "config_path": "...",
  "token_present": true,
  "token_fingerprint": "a1b2c3d4",
  "token_valid": null
}

If token_present is false, run init first.

Save a token (agent-recommended method)

printf "%s" "$NOTION_TOKEN" | solid-notion init --token-stdin --json

Returns on success:

{
  "ok": true,
  "action": "init",
  "profile": "default",
  "config_path": "...",
  "token_saved": true,
  "overwritten": false,
  "ignored_inputs": [],
  "dry_run": false
}

Other token input methods (in precedence order):

Additional flags:

Remove a token

solid-notion auth logout --json

2. Command Reference

2.1 Browse

List locally pulled pages

solid-notion ls
solid-notion ls --json

Lists all pages that have been pulled to $SOLID_NOTION_HOME/. Does not call the Notion API.

Default output: tab-separated <pulled_at>\t<page_id>\t<title>, sorted newest first.

JSON output (--json): array of objects with page_id, title, pulled_at, path.

List all pages (remote)

solid-notion pages

Output: tab-separated lines of <last_edited>\t<page_id>\t<title>.

Search pages

solid-notion search <query>

Output: same tab-separated format as pages.

2.2 Read

Show a page (non-recursive, stdout)

solid-notion show page <page_id_or_name> --format markdown
solid-notion show page <page_id_or_name> --format json

<page_id_or_name> can be a UUID or a page title. Default format: markdown.

Show a block (JSON only)

solid-notion show block <block_id> --format json

Pull a page to local files

solid-notion pull page <page_id_or_name> --format markdown --outdir ./output

Options:

Outputs the path of the written file.

If the page was already pulled locally, running pull page again fetches the latest content from Notion and overwrites local output files in that directory.

Pull a block to local file

solid-notion pull block <block_id> --outdir ./output

Options: --outdir <dir>, --no-recursive

2.3 Edit and Write

All edit/write/submit commands require a strict Notion page ID (UUID format like aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee). Page names are NOT accepted.

Apply a JSON patch

Pipe a JSON patch object to stdin:

echo '{"ops": [...]}' | solid-notion edit <page_id>

Also accepts a markdown file path (notion-page-<uuid>.md) to resolve the page ID.

CRITICAL: Valid Patch Schema

The patch object must have exactly these keys: ops (array) and notes (string). No other keys allowed.

{
  "ops": [
    { "op": "replace_block_text", "block_id": "...", "new_markdown": "...", "reason": "..." },
    { "op": "append_blocks", "parent_block_id": "...", "blocks": [...], "reason": "..." },
    { "op": "set_props", "page_id": "...", "set": {...}, "reason": "..." }
  ],
  "notes": "optional notes"
}

Three allowed operation types:

replace_block_text

Replaces rich_text content of a block. Supported block types:

paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, to_do, quote, callout

{
  "op": "replace_block_text",
  "block_id": "block-uuid",
  "new_markdown": "## New heading",
  "reason": "Clarified section title"
}

append_blocks

Appends new blocks under a parent block.

• Most block types need type + rich_text_md
• divider needs only type
• code supports optional language (defaults to plain text)

{
  "op": "append_blocks",
  "parent_block_id": "parent-uuid",
  "blocks": [
    { "type": "paragraph", "rich_text_md": "New paragraph content" },
    { "type": "heading_2", "rich_text_md": "New section" }
  ],
  "reason": "Added conclusion section"
}

Allowed block types:

• paragraph, heading_1, heading_2, heading_3
• bulleted_list_item, numbered_list_item, to_do, quote, callout
• code, divider

set_props

Updates page properties (title, rich_text, number, checkbox, select, multi_select, date).

{
  "op": "set_props",
  "page_id": "page-uuid",
  "set": {
    "Status": { "type": "select", "name": "Done" },
    "Priority": { "type": "number", "value": 3 },
    "Done": { "type": "checkbox", "value": true },
    "Tags": { "type": "multi_select", "names": ["urgent", "important"] },
    "Due Date": { "type": "date", "start": "2026-03-02", "end": null },
    "Title": { "type": "title", "md": "New page title" },
    "Notes": { "type": "rich_text", "md": "Some notes" }
  },
  "reason": "Updated status to Done"
}

Property value types:

Write workspace changes back to Notion

solid-notion write <page_id>

Reads the workspace files (page.md, .original.md), replaces the page content in Notion, creates a changeset, and cleans up the workspace.

Submit pending edits with rollback

solid-notion submit <page_id> -m "description of changes"

CRITICAL: How submit works

submit consumes pending edit logs (created by previous edit commands) and applies them to Notion with transaction-like semantics:

1. Phase 0: Load — Reads all edit log files from edit-logs/<page_id>/ that don't have .submitted markers
2. Phase 1: Prepare — Fetches before-snapshots (current block content, property values) so rollback is possible
3. Phase 2: Apply — Applies ops sequentially to Notion
4. Phase 3: Finalize — On success, saves commit to versions/. On failure, rolls back already-applied ops using before-snapshots.

Exit statuses:

Submit result format:

{
  "ok": true,
  "commit_id": "cmt_20260302_143022",
  "notion_id": "3d1b-...",
  "status": "pushed",
  "applied_ops": 3,
  "included_edits": 2
}

Best practices:

• Always run submit after edit operations to publish changes
• If submit returns rolled_back, the page is back to original state — no manual cleanup needed
• If submit returns failed_needs_reconcile, manual intervention may be required
• The -m (message) flag is required

2.4 Create New Pages

CRITICAL: Use the new command to create Notion pages programmatically

The new command creates a new page under a parent (page or database) with metadata only (title, icon, cover, props) via stdin as JSON. After creation, the page is automatically pulled locally as markdown. To add content (blocks), use the existing edit + submit workflow.

Create a new page

echo '{"title":"My New Page","notes":""}' | solid-notion new --parent <parent_id> -m "Create page" --json

Required flags:

• --parent <parent_id> — Parent page or database ID
• -m, --message <message> — Commit message

Optional flags:

• --database — Parent is a database (creates as database entry)
• --json — Output JSON only
• --dry-run — Validate without creating

CRITICAL: Valid Payload Schema

The JSON payload via stdin must have exactly these keys:

{
  "title": "Page Title",
  "icon": { "type": "emoji", "emoji": "📝" },
  "cover": { "type": "external", "url": "https://..." },
  "props": {
    "Status": { "type": "select", "name": "In Progress" }
  },
  "notes": "optional notes about this creation"
}

Required fields:

• title (string, non-empty)
• notes (string, can be empty)

Optional fields:

• icon — { "type": "emoji", "emoji": "🎉" } or { "type": "external", "url": "..." }
• cover — { "type": "external", "url": "..." }
• props — Page properties (database entries), same types as set_props plus url, email, phone_number

No blocks field. Content is added via edit + submit after creation.

Property types for props (database entries):

All types from set_props plus:

• url: { "type": "url", "value": "https://..." }
• email: { "type": "email", "value": "user@example.com" }
• phone_number: { "type": "phone_number", "value": "+1234567890" }

CRITICAL rules:

• Payload must have exactly title, notes, and optional fields — no extra keys
• For database pages, props must match the database schema
• After creation, the page is auto-pulled locally as markdown

Transaction semantics:

new follows the same 4-phase pipeline as submit:

1. Phase 0: Parse — Read and validate JSON from stdin
2. Phase 1: Prepare — Verify parent exists, derive internal ops, create commit draft
3. Phase 2: Apply — Create page on Notion (metadata only)
4. Phase 3: Finalize — Persist version record, auto-pull page. On failure, rollback (archive page).

Rollback for new:

• Archives the created page (soft-delete)

Success output (JSON mode):

{
  "ok": true,
  "commit_id": "parent-id-20260304T120000Z",
  "action": "new",
  "status": "pushed",
  "created_page_id": "abc123-def456",
  "page_url": "https://notion.so/abc123def456",
  "title": "My New Page",
  "parent_id": "parent-id",
  "parent_type": "page",
  "pulled_to": "/path/to/notion-page-abc123-def456.md"
}

Dry run output:

{
  "ok": true,
  "action": "new",
  "status": "dry_run",
  "dry_run": true,
  "validation": "passed",
  "title": "My New Page",
  "parent_id": "parent-id"
}

2.5 History and Restore

View history

solid-notion history <page_id>

Output: tab-separated <id>\t<created_at>\t<type>.

Types:

• changeset — Created by write or restore
• new — Created by new command
• submit — Created by submit command

Restore to a previous changeset or version

solid-notion restore <page_id> <changeset_or_commit_id>
solid-notion restore <changeset_or_commit_id>

Behavior depends on type:

• Changeset (from write/restore): Restores page to that changeset's state
• Version (submit or new): Restore to the target hash by undoing only the later submit versions, then writes a new changeset

Hash-only lookup is supported. If the hash exists in multiple pages, CLI asks you to disambiguate with page ID.

After restore-to-version, local version files after the target hash are deleted.

Outputs the new changeset ID created by restore.

3. Agent Workflows

Workflow: Read a page as Markdown

solid-notion pull page <page_id_or_name> --format markdown --outdir /tmp/notion-work

Then read the output file path printed to stdout.