icloud-md

Apple Notes, checked out to ./notes. As plain Markdown. Even on Linux.

Bi-directional sync between iCloud Notes and a folder of real files — diffable, greppable, git-trackable, editor-agnostic. A git-flavored CLI for Linux, Windows, and macOS.

$ npm install -g icloud-md

why files

Notes.app is a fine place to write. It shouldn’t be the only place your notes exist.

Apple Notes lives in exactly one place: Notes.app and the iCloud web client. No export, no API, no way to bring your own tooling. icloud-md checks your notes out into the filesystem, where twenty-five years of text tooling already works — and pushes your edits back as if you'd typed them into Notes.app all along.

The working directory is the local state. Wrap it in git and you have history, blame, and off-site backup for every note you’ve ever taken — including the ones other people share with you.

features

bi-directional sync

pull merges remote edits into your local ones; push sends creates, edits, moves, and deletes back up. A note that changed remotely is reported as a conflict, never silently overwritten.

no Mac required

A plain Node CLI, not an AppleScript wrapper. Clone to Linux or Windows and treat your notes like any other folder of text — nothing to install on your phone, nothing running in the background.

rich text round-trips

Headings, nested lists, checklists, blockquotes, code blocks, links, bold/italic — real Markdown down, real Apple formatting back up. Tables too.

shared notes

Notes and folders shared with you clone under a directory per sharer. Creates and edits push back into shared folders you can write to.

history / diff / revert

Every sync that changes a note snapshots it first. Inspect any past version, diff two, or write one back to the server.

careful by default

status shows exactly what a push would do before it does it. Every write is round-trip verified byte-for-byte, and anything the tool can’t fully parse stays read-only. Ambiguity is an error, not a coin flip.

quickstart

# requires Node.js 20+
npm install -g icloud-md

# first clone opens Apple's real sign-in page (password, 2FA)
icloud-md clone ./notes

cd notes
icloud-md status     # what would push do?
icloud-md pull       # merge down remote edits
icloud-md push       # send local edits up

using obsidian?

A cloned vault is already just Markdown, so Obsidian can open it as-is. Two things make the fit exact:

the Apple Notes Sync plugin — a thin Obsidian front-end for this CLI, in the community plugin browser (source). Connect a folder, then pull and push from the ribbon, the command palette, or the status bar — and optionally on a schedule. Desktop only; it shells out to icloud-md.
--filename-as-title — clone with this flag and each file is named for its note's title and holds only the body, which is the shape Obsidian expects. Renaming a file then retitles the note.

Obsidian's own notation survives the round trip in either shape: wikilinks and embeds, callouts, #tags, ==highlights== and footnotes keep their spelling on disk instead of collecting the backslashes plain Markdown would want. YAML frontmatter is treated as local metadata — add aliases and tags freely; they stay on your machine and never look like a note change.

versus everything else

	icloud-md	AppleScript / Notes.app tools	NoteStore.sqlite parsers
Runs off-Mac	yes	no	needs a copied DB
Writes notes back	yes	some	read-only
Reconciles both sides	yes — merges, conflicts, locks	no	no
Native Markdown	yes	generic rich text	varies
Shared notes	read + write	no	read-only

caveat emptor: not an official Apple API — this is a reverse-engineering of the private CloudKit service iCloud.com itself uses, and Apple can change it any time. Writes are verified byte-for-byte and refusals are the failure mode, but keep the clone in git, test on a disposable note first, and note that Advanced Data Protection accounts aren’t supported. MIT licensed.