Manage Notion pages locally as Markdown: pull, edit with JSON patches, write changes, submit edits with rollback, and handle API authentication via solid-not...
solid-notion is a CLI for reading, editing, and writing Notion pages as Markdown with local reversible changesets.
For normal usage (published package):
npm install -g solid-notion
solid-notion --version
For local development from source:
pnpm install
pnpm build
Before using any command that talks to Notion, a token must be configured.
Create a Notion integration to get an API token:
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.
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):
| Method | Flag | Notes |
|---|---|---|
| Direct | --token <value> | Visible in ps / shell history |
| Stdin | --token-stdin | Recommended for agents |
| JSON | --input-json '{"token":"..."}' | Useful for structured protocols |
Additional flags:
| Flag | Effect |
|---|---|
--json | Machine-readable JSON output only |
--dry-run | Preview without writing |
--force | Overwrite existing token |
--profile <name> | Use a named profile (default: "default") |
solid-notion auth logout --json
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.
solid-notion pages
Output: tab-separated lines of <last_edited>\t<page_id>\t<title>.
solid-notion search <query>
Output: same tab-separated format as pages.
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.
solid-notion show block <block_id> --format json
solid-notion pull page <page_id_or_name> --format markdown --outdir ./output
Options:
| Flag | Default | Description |
|---|---|---|
--format <format> | json | json or markdown |
--outdir <dir> | $SOLID_NOTION_HOME/<page_id> | Output directory |
--no-local-images | (images downloaded) | Skip downloading images |
--no-local-videos | (videos downloaded) | Skip downloading videos |
--no-recursive | (recursive) | Only first-level blocks |
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.
solid-notion pull block <block_id> --outdir ./output
Options: --outdir <dir>, --no-recursive
All edit/write/submit commands require a strict Notion page ID (UUID format like aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee). Page names are NOT accepted.
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_textReplaces 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_blocksAppends new blocks under a parent block.
type + rich_text_mddivider needs only typecode 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_3bulleted_list_item, numbered_list_item, to_do, quote, calloutcode, dividerset_propsUpdates 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:
| Type | Shape | Example |
|---|---|---|
number | { "type": "number", "value": 42 } | - |
checkbox | { "type": "checkbox", "value": true } | - |
select | { "type": "select", "name": "Option" } | - |
multi_select | { "type": "multi_select", "names": ["A", "B"] } | - |
date | { "type": "date", "start": "2026-03-02", "end": null } | end optional |
title | { "type": "title", "md": "markdown" } | - |
rich_text | { "type": "rich_text", "md": "markdown" } | - |
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.
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:
edit-logs/<page_id>/ that don't have .submitted markersversions/. On failure, rolls back already-applied ops using before-snapshots.Exit statuses:
status | Meaning | ok |
|---|---|---|
pushed | All ops applied successfully | true |
nothing_to_submit | No pending edits found | false |
rolled_back | Apply failed but rollback succeeded | false |
failed_needs_reconcile | Apply failed AND rollback partially failed | false |
Submit result format:
{
"ok": true,
"commit_id": "cmt_20260302_143022",
"notion_id": "3d1b-...",
"status": "pushed",
"applied_ops": 3,
"included_edits": 2
}
Best practices:
submit after edit operations to publish changesrolled_back, the page is back to original state — no manual cleanup neededfailed_needs_reconcile, manual intervention may be required-m (message) flag is requiredCRITICAL: 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.
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 messageOptional flags:
--database — Parent is a database (creates as database entry)--json — Output JSON only--dry-run — Validate without creatingCRITICAL: 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_numberNo 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:
title, notes, and optional fields — no extra keysprops must match the database schemaTransaction semantics:
new follows the same 4-phase pipeline as submit:
Rollback for new:
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"
}
solid-notion history <page_id>
Output: tab-separated <id>\t<created_at>\t<type>.
Types:
changeset — Created by write or restorenew — Created by new commandsubmit — Created by submit commandsolid-notion restore <page_id> <changeset_or_commit_id>
solid-notion restore <changeset_or_commit_id>
Behavior depends on type:
write/restore): Restores page to that changeset's statesubmit or new): Restore to the target hash by undoing only the later submit versions, then writes a new changesetHash-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.
solid-notion pull page <page_id_or_name> --format markdown --outdir /tmp/notion-work
Then read the output file path printed to stdout.
Pull the page to a workspace:
solid-notion pull page <page_id> --format markdown --outdir ~/.local/share/solid-notion-cli/<page_id>
Edit the local page.md file as needed.
Write changes back:
solid-notion write <page_id>
Submit with a message:
solid-notion submit <page_id> -m "Updated section headings"
Use this workflow when making precise, targeted edits without pulling full markdown.
Get the target block IDs (you may need to pull JSON first):
solid-notion pull page <page_id> --format json --outdir /tmp
# or inspect specific block:
solid-notion show block <block_id> --format json
Construct a valid patch with ops array and notes:
{
"ops": [
{
"op": "replace_block_text",
"block_id": "block-uuid-here",
"new_markdown": "Updated content here",
"reason": "Clarified the explanation"
},
{
"op": "set_props",
"page_id": "page-uuid-here",
"set": {
"Status": { "type": "select", "name": "In Progress" }
},
"reason": "Moving to next phase"
}
],
"notes": "Batch update from review session"
}
Apply the patch via stdin:
cat patch.json | solid-notion edit <page_id>
Submit the pending edits:
solid-notion submit <page_id> -m "Applied review feedback"
CRITICAL rules for JSON patch editing:
ops and notes — no extra keysop, reason, and type-specific fieldsblock_id in replace_block_text must be a valid Notion block IDpage_id in set_props must be the target page UUIDappend_blocks creates new blocks — the created_block_ids are recorded in edit logs for rollbackYou can run multiple edit commands before a single submit. All pending edits are aggregated:
# First edit
echo '{"ops":[...],"notes":"First change"}' | solid-notion edit <page_id>
# Second edit
echo '{"ops":[...],"notes":"Second change"}' | solid-notion edit <page_id>
# Third edit
echo '{"ops":[...],"notes":"Third change"}' | solid-notion edit <page_id>
# Submit all at once
solid-notion submit <page_id> -m "Batch: three related updates"
Submit reads all edit logs from edit-logs/<page_id>/, marks them .submitted on success, and creates a single commit record.
List changesets:
solid-notion history <page_id>
Restore to a specific hash:
solid-notion restore <page_id> <changeset_or_commit_id>
# or hash-only when unique:
solid-notion restore <changeset_or_commit_id>
All data is stored under $SOLID_NOTION_HOME (default: ~/.local/share/solid-notion-cli).
Workspace files (<page_id>/) — Created by pull, used by write:
page.md — The markdown you edit.original.md — Snapshot before editing (for diff/comparison)page.meta.md — Page metadata (properties, etc.)pull, deleted on successful writeEdit logs (edit-logs/<page_id>/) — Created by edit, consumed by submit:
op, block_id/page_id, reason, and before/after valuesedit, marked .submitted on successful submitVersions (<page_id>/versions/) — Created by submit:
commitId, status, ops, beforeSnapshots, applyStatesubmit attempt (even failures)Changesets (changesets/<page_id>/) — Created by write and restore:
history and restorewrite, referenced by history and restore$SOLID_NOTION_HOME/
config.json # Auth tokens (mode 0600)
# Workspace (markdown editing workflow)
<page_id>/
page.md # Edited markdown
page.meta.md # Page metadata
.original.md # Original for diff
versions/ # Submit commits (JSON)
# Edit logs (JSON patch workflow)
edit-logs/<page_id>/
<page_id>-<timestamp>.jsonl # Pending edits (before submit)
<page_id>-<timestamp>.jsonl.submitted # Marker file (after submit)
# Changesets (restorable full-page versions)
changesets/<page_id>/
<page_id>-<timestamp>.md # Changeset with YAML frontmatter
Override the base directory with SOLID_NOTION_HOME environment variable.
| Flag | Effect |
|---|---|
-v, --verbose | Print debug logs to stderr |
-V, --version | Print version |
| Exit code | Error | Meaning |
|---|---|---|
| 2 | missing_arguments | No token provided |
| 3 | invalid_token | Token is empty or invalid |
| 4 | token_already_exists | Token exists, use --force |
| 5 | write_failed | Could not write config file |
All other commands exit 1 on failure and print diagnostics to stderr including error name, message, metadata (status, code, errno, syscall, hostname), cause chain, and stack trace.
--token <value> in automated flows. Use --token-stdin to avoid leaking tokens in process lists.solid-notion auth status --json before running commands. If there is no token, all Notion API calls will fail.edit, write, submit, history, or restore. These commands require strict page UUIDs.--json when you need to parse command output programmatically.submit without -m. The message flag is required.submit takes stdin — it reads from local edit-logs/, not from stdin.status: "rolled_back" — this means Notion writes failed but were undone.status: "failed_needs_reconcile" — this means both apply AND rollback failed.ops and notes allowed).reason field in each op — it is required.replace_block_text or append_blocks.set_props on properties with unsupported types (only: number, checkbox, select, multi_select, date, title, rich_text).new_markdown — pass simple Markdown text (e.g., "## Heading" or "Paragraph with bold").ZIP package — ready to use