Skip to content

iCloud Sync

FoldNotes stores your notes in iCloud Drive, so they sync automatically across your devices.

How It Works

  1. Files are the source of truth. Your notes are plain .md files in iCloud Drive. Any app or device that can read iCloud Drive can access them.
  2. Automatic detection. FoldNotes uses NSMetadataQuery to monitor the collection folder for changes. When a file is added, modified, or deleted on another device, FoldNotes updates its index.
  3. Incremental updates. Only changed files are processed — the entire collection isn't re-scanned on every sync.

Collection Location

~/Library/Mobile Documents/iCloud~com~foldnotes/Documents/

This is the standard iCloud Drive container. Files placed here by any means (Finder, CLI, another app) are picked up by FoldNotes.

Conflict Resolution

If the same note is edited on two devices before syncing, iCloud creates a conflict file. FoldNotes detects conflict files and shows a conflict resolution panel that lets you:

  • View both versions side by side
  • Choose which version to keep
  • Merge changes manually

Offline Access

Notes are available offline — iCloud Drive keeps local copies of your files. Edits made offline sync when connectivity is restored.

Fallback

If you're not signed in to iCloud, FoldNotes stores notes in a local collection at:

~/Documents/FoldNotes/

Notes stored locally won't automatically sync. Sign in to iCloud Drive to enable sync for new notes. If you have existing local notes, you will have to copy them.

You can also specify a custom collection location using the CLI's --collection option.

SwiftData Cache

FoldNotes maintains a local SwiftData cache for fast queries (tags, tasks, backlinks, search). This cache is derived from the .md files and is rebuilt automatically when needed. The cache is not synced — each device builds its own.

If the cache becomes stale, use File → Rebuild Note Index… to force a full rebuild.