apple-notes-md-sync

One-way sync from Apple Notes to a folder of Markdown files. Runs locally on macOS, reads the Apple Notes database directly, and writes clean Markdown that mirrors your Notes folder hierarchy.

Your notes never leave your machine. The tool only reads Apple Notes and writes Markdown to a folder you choose.

Features

• One-way sync: Apple Notes → Markdown folder.
• Mirrors the Apple Notes folder hierarchy locally.
• Maps tag-based Smart Folders to local folders.
• Exports attachments to _attachments/<note-id>/.
• Incremental: tracks state and only writes what changed.
• Protects local edits with SHA-256 hashes — conflicted files are skipped unless --force.
• Safe by default: --dry-run previews every operation.

Requirements

• macOS — reads the local Apple Notes container.
• Node.js >= 18.
• sqlite3 on your PATH (ships with macOS; otherwise brew install sqlite).
• Full Disk Access for the terminal/app running the command, so it can read the Apple Notes database.

Full Disk Access: System Settings → Privacy & Security → Full Disk Access → enable your terminal app.

Install

npm install -g apple-notes-md-sync

Or run it without installing:

npx apple-notes-md-sync --out ~/Notes

Usage

apple-notes-md-sync --out ~/Notes

The first sync must target an empty folder. The tool refuses to start otherwise, so existing files are never duplicated. Later runs reuse the same folder.

Preview without writing anything:

apple-notes-md-sync --out ~/Notes --dry-run

See all options:

apple-notes-md-sync --help

Options

| Flag | Description | |---|---| | --out <dir> | Output folder for the generated Markdown (required). | | --source <dir> | Read from a copied Apple Notes data folder (default: ~/Library/Group Containers/group.com.apple.notes). | | --dry-run | Print operations without writing changes. | | --delete-missing | Delete managed files for notes/attachments no longer in Apple Notes. | | --force | Overwrite or delete even when local edits are detected. | | --include-trash | Include Recently Deleted notes. | | --keep-first-line | Keep Apple Notes' title line in the note body. | | --include-handwriting | Include detected handwriting text. | | --prefix <format> | Prefix exported filenames with the creation date (e.g. YYYY-MM-DD). | | -h, --help | Show help. | | -v, --version | Show the version. |

How it works

• Notes are written into the Apple Notes folder hierarchy under --out.
• Tag-based Smart Folders are mapped to local folders.
• Attachments are written to _attachments/<note-id>/.
• Sync state is stored in .apple-notes-export-state.json inside the output folder.
• A lock file .apple-notes-export.lock prevents concurrent runs.
• Local edits are detected via SHA-256 hashes; conflicted files are skipped unless --force is used.

Sync state

The sync is incremental. After each run the tool writes .apple-notes-export-state.json in the output folder, recording for every note and attachment the file it maps to, its location, and a content hash. The next run reads this file to write only what changed, move renamed files, and — with --delete-missing — remove notes that disappeared from Apple Notes.

Keep this file with the Markdown; it is part of the output folder:

• First run must target an empty folder. The tool refuses to start otherwise, so existing files are never duplicated.
• If the state file is deleted while the Markdown remains, the tool no longer recognizes those files and refuses to run into the now non-empty folder. Restore the state file, or start fresh from an empty folder.
• If the state file is corrupted, the tool stops with an error instead of re-syncing blindly.

Development

git clone https://github.com/YassineBenh/apple-notes-md-sync.git
cd apple-notes-md-sync
npm install
npm run dev -- --out ~/Notes --dry-run   # run from source via tsx
npm run build                            # bundle to dist/cli.js
npm run typecheck

Acknowledgements

The Apple Notes protobuf schema in descriptor.ts is derived from the Obsidian Importer project (MIT). See THIRD-PARTY-NOTICES.md.

License

MIT © Yassine Benhamouda