Your Apple Notes, now editable as plain Markdown files (no Mac required)
Apple Notes only live in one place: Notes.app or the iCloud web client. They don't provide a documented API to access your notes from anywhere else. That's been a persistent annoyance for me because my husband likes to plan things collaboratively using Apple Notes, and my only Apple product is an iPhone ... so my half of the planning was happening on a phone keyboard or in a clunky web interface while a perfectly good computer running my favorite Markdown editor (Obsidian) sat in front of me. I wanted my notes to be real files that I could edit alongside my other notes, so I built icloud-md: a CLI that clones your notes into a folder of Markdown and syncs your edits back to iCloud as if you'd typed them into Notes.app all along.
icloud-md clone ./my-notes
cd my-notes && vim "Grocery list.md"
icloud-md push
What that gets you:
- Real files: one Markdown file per note — greppable, diffable, git-trackable, editable in whatever you already use. Your Notes folder structure becomes real directories, and
mkdir+pushcreates folders upstream. - Any OS: it's a plain Node CLI talking to iCloud directly, not an AppleScript wrapper around a live Notes.app or a parser for a database you had to copy off a Mac first. Linux and Windows work great!
- Actually bidirectional:
pulldoes a real three-way merge when a note changed both remotely and locally, only asking you to resolve the parts that overlap.pushhandles creates, edits, moves, and deletes, and a note that changed remotely since your last sync is reported as a conflict, never silently overwritten. - Formatting round-trips: headings, nested lists, checklists, blockquotes, tables (yes, edits push back), inline formatting.
- Careful by default:
statusshows exactly what a push would do first, every write is round-trip verified, and anything the tool can't fully account for in a note's internal format stays read-only rather than getting a hopeful best-effort write.
I'm a Staff Engineer at the company I work at, and I've done a lot of software over the years. I'd wanted to spend some time reverse-engineering the CloudKit protocol, and was honestly never going to find that time. But, as I'm sure you're all aware, the world has changed over the last year, and the fact that a reverse-engineering project provides a really solid, clear feedback loop meant that I had a new approach I could take: coaching an LLM (in this case: Fable 5) into building that feedback loop, and then tasking it with exercising parts of the iCloud (and later: iPhone) Apple Notes UI so that it could reverse-engineer the protocol. This was a surprisingly large amount of fun and it goes to show you that what you get out of AI tooling scales well with what experience the person wielding it brings to the table; neither of us was getting through Apple's protobuf-and-CRDT note format alone on a weekend.
MIT, TypeScript/Node: https://github.com/coddingtonbear/icloud-md & https://coddingtonbear.github.io/icloud-md/